Jira Changelog Generator
Generates a changelog of Jira issues from your git history and, optionally, attach all issues to a release.
For example:
$ jira-changelog --range origin/prod...origin/master
Jira Tickets
---------------------
* <Bug> - Unable to access date widget
[DEV-1234] https://yoursite.atlassian.net/browse/DEV-1234
* <Story> - Support left-handed keyboards
[DEV-5678] https://yoursite.atlassian.net/browse/DEV-5678
* <Story> - Search by location
[DEV-8901] https://yoursite.atlassian.net/browse/DEV-8901
Other Commits
---------------------
* <cd6f512> - Fix typo in welcome message
Pending Approval
---------------------
~ None. Yay! ~
You can also have it automatically post to slack!
How it works
The script looks for Jira issue keys, surrounded by square brackets (i.e. [DEV-123]), in the git commit logs. When it finds one, it associates that Jira issue ticket with that commit and adds it to the changelog.
Installation
npm install -g jira-changelog
JIRA setup
Before configuring the app, register a new user in Jira for the app to use to retrieve and update tickets. Then create an Auth Token for this user, which will be used for authentication. Jira no longer supports authenticating with password for API calls.
Configuration
Create a file called changelog.config.js and put it at the root of your git workspace directory. This is also where you'll call the jira-changelog command from.
Here's a simple example with sample Jira API values:
module.exports = {
jira: {
api: {
host: 'myapp.atlassian.net',
email: 'jirauser@myapp.com',
token: 'qWoJBdlEp6pJy15fc9tGpsOOR2L5i35v',
options: {}
},
}
}
The token is the API token assigned to this user. To see all values supported, look at the changelog.config.js file at the root of this repo.
Use the options object to set jira-client options. See official docs for available options.
Usage
jira-changelog --range origin/prod...origin/master
Assuming you deploy from a branch named prod, this will generate a changelog with all commits after the last production deploy to the current master version (You can change the default branch names with the sourceControl.defaultRange object, in your config).
jira-changelog
Alternatively, you can specify a range (using git commit range format) in the command:
jira-changelog --range origin/prod...origin/stage
Releases
You can automatically attach a release to all Jira issues in the changelog with the --release flag. For example, let's say we want to add all issues in the changelog to the "sprint-12" release:
jira-changelog --release sprint-12
This will set the fixVersions of all issues to "sprint-12" in Jira.
Slack
The script can also automatically post the changelog to slack.
First, get an API token from Slack for your workspace:
https://api.slack.com/tokens
Then add slack to your configuration file:
module.exports = {
...
slack: {
apiKey: 'asdlfkjasdoifuoiucvlkxjcvoixucvi',
channel: '#changelogs'
},
}
- Add your API token to
slack.apiKey.
slack.channel is the channel you want the script to send the changelog to.
Then simply add the --slack flag to the command:
jira-changelog --slack
API
The code used to generate the changelogs can also be used as modules in your node app.
See the module source for documentation.
For example:
npm install -S jira-changelog
const Config = require('jira-changelog').Config;
const SourceControl = require('jira-changelog').SourceControl;
const Jira = require('jira-changelog').Jira;
const gitRepoPath = '/home/user/source/'
// Get configuration
const confPath = `${gitRepoPath}/changelog.config.js`;
const config = Config.readConfigFile('/Users/jeremygillick/Source/app/changelog.config.js');
// Get commits for a range
const source = new SourceControl(config);
const range = {
from: "origin/prod",
to: "origin/master"
};
source.getCommitLogs(gitRepoPath, range).then((commitLogs) => {
// Associate git commits with jira tickets and output changelog object
const jira = new Jira(config);
jira.generate(commitLogs).then((changelog) => {
console.log(changelog);
});
});
Tips & Tricks
Change the output
The output of the changelog is controlled by an ejs template defined in your changelog.config.js file. You can see the default template, here:
https://github.com/jgillick/jira-changelog/blob/master/changelog.config.js#L95-L136
The data sent to the template looks like this:
{
jira: {
baseUrl: "...",
releaseVersions: [],
},
commits: {
all: [], // all commits
tickets: [], // commits associated with jira tickets
noTickets: [], // commits not associated with jira tickets
},
tickets: {
all: [], // all tickets
approved: [], // tickets marked as approved
pending: [], // tickets not marked as approved
pendingByOwner: [], // pending tickets arranged under ticket reporters.
}
}
The template should output data only, not perform data transformations. For that, define the transformData or transformForSlack functions.
Custom data transformation
What if you want to edit the git commit log messages to automatically add links around the ticket numbers? You can do that, and more, by defining the transformData function inside your changelog.config.js file. This function can transform all the template data, before it is sent to the template.
For example, adding a link around all ticket numbers in the git logs would look something like this (overly simplistic, for example only):
transformData: (data) => {
// Link the ticket numbers in all commit summaries.
data.commits.all.forEach((commit) => {
commit.summary = commit.summary.replace(
/\[([A-Z]+\-[0-9]+)\]/,
'[<a href="https://YOU.atlassian.net/browse/$1">$1</a>]'
);
});
return data;
},
Then, if you want to create slack specific data transformations, define the transformForSlack function. This function will be called after transformData.
