Release Notes Generator

An Azure DevOps extension that generates release notes from a git commit range. This task analyses merge commits to extract the pull request IDs, which are then used to call Azure DevOps APIs to get the pull request data and the associated work items.
Only works with squash merges, as it operates based on the commit message. It finds the PR ID from commit messages in the format: Merged PR {id}: {title}
.
How to use it
- task: ReleaseNotes@2
inputs:
startCommit: 'v1.0.0'
endCommit: 'HEAD'
outputFileMarkdown: '$(Build.ArtifactStagingDirectory)/release-notes.md'
outputFileHtml: '$(Build.ArtifactStagingDirectory)/release-notes.html'
- Once the task has finished both a markdown and a html file will be generated. Which can then be used/ saved -
- task: PublishBuildArtifacts@1
inputs:
PathtoPublish: '$(Build.ArtifactStagingDirectory)'
ArtifactName: 'release-notes'
publishLocation: 'Container'
Parameters
Parameter |
Description |
Required |
Default |
startCommit |
Commit reference for the start of the range (exclusive). Can be a commit hash, git tag, or a ref like HEAD or HEAD~xx |
✅ |
- |
endCommit |
Commit reference for the end of the range (inclusive). Can be a commit hash, git tag, or a ref like HEAD or HEAD~xx |
✅ |
HEAD |
outputFileMarkdown |
Path for markdown output |
✅ |
$(Build.ArtifactStagingDirectory)/release-notes.md |
outputFileHtml |
Path for HTML output |
✅ |
$(Build.ArtifactStagingDirectory)/release-notes.html |
templateFileMarkdown and templateFileHtml |
Path to custom Handlebars template file |
❌ |
Built-in template |
- Commit hash (e.g.,
a1b2c3d
)
- Git tag (e.g.,
v1.0.0
)
HEAD
or HEAD~xx
(where xx
is the number of commits before HEAD)
Output
The task generates both a markdown and an interactive HTML file, using the default templates. You can see the default templates here - Markdown/ HTML.
Here is what the templates look like -
| Markdown | HTML |
|---|---|
|
|
|
Template Customisation
The task uses Handlebars templates to format output. You can provide a custom template file or use the built-in default template.
There are some built-in Handlebars helpers -
Template Data Structure
Your template has access to the following data, via TemplateData
object:
interface TemplateData {
commits: Commit[];
workItems: WorkItemList[];
pullRequests: PullRequest[];
startCommit: string;
endCommit: string;
generatedDate: string;
repositoryId?: string;
project?: string;
}
interface Commit {
hash: string;
author: string;
email: string;
date: string;
subject: string;
body: string;
pullRequest?: PullRequest;
}
interface PullRequest {
id: number;
title: string;
url: string;
author: string;
workItems: WorkItem[];
}
interface WorkItem {
id: string;
title: string;
workItemType: string; // e.g., "User Story", "Bug", "Task"
url: string;
assignedTo: {
displayName: string;
uniqueName: string;
imageUrl: string;
};
}
interface WorkItemList {
id: string;
title: string;
workItemType: string;
url: string;
assignedTo: {
displayName: string;
uniqueName: string;
imageUrl: string;
};
pullRequests: PullRequest[];
}
Local testing
The task can also be run from the command line for testing out custom templates.
- Clone the repo
- Run
npm run build
, in the CommitRangeReleaseNotesTask
folder
- Run the following command from the folder
CommitRangeReleaseNotesTask\task\dist
node ./mainConsole.js
--startCommit "v1.0.0"
--endCommit "HEAD"
--outputFileMarkdown "C:\release-notes.md"
--outputFileHtml "C:\release-notes.html"
--repoRoot "\path\to\repo"
--systemAccessToken "your-token"
--project "your-project"
--repositoryId "your-repo"
--apiUrl "https://dev.azure.com/your-org"
To test locally, the systemAccessToken
will need to be a Personal Access Token (PAT).