If like Stef you’re using a local branch per JIRA issue, you might want the following features:
- Make all commits in that branch include the JIRA issue name and description.
- The ability to start a branch for a JIRA issue which would mark the issue as In Progress.
- The ability to merge a branch for a JIRA issue which would mark the issue as Fixed.
This can all be automated and we describe how to set this up.
You need to Administer JIRA and allow it to Accept remote API calls.
Then you will probably want to create a special user with very limited permissions, let’s say “cli-api” (or “cli-api-stef” if you want one API user per user), in a new group called “api-users”.
Next, edit the “Permission Scheme” of the project you want to allow access to, and grant the following permissions to the “api-users”
group:
| Permission Name | What for |
|---|---|
| Browse Projects | Required for everything |
| Assign Issues | Required for starting and merging branches |
| Resolve Issue | Required for starting and merging branches |
On the JIRA side you’re all set.
Download it (the “Download Binary” link at the bottom), and save it somewhere appropriate on your system.
You now need to tell our tools how to connect to JIRA:
# Run this INSIDE your project (or make it --global if you prefer)
$ git config jira.cli ~/bin/jira-cli-2.4.0/jira.sh
$ git config jira.user cli-api
$ git config jira.password secret
$ git config jira.server https://jira.lunatech.com/jira
Download the custom hook and install it in your project at .git/hooks/prepare-commit-msg.
Download git-jirabranch and git-jirafix and put them somewhere on your path, so that git picks them up as git extensions.
$ git jirabranch FOO-23
This will do the following:
- Create a branch called FOO-23
- Switch to the new branch
- Mark the FOO-23 issue as in progress
- Add a comment to FOO-23 saying you started working on it
$ echo "new" > new-file
$ git commit new-file
Your message will start with those lines:
# [FOO-23]: Do tons of fixes
# [jira]
# View this issue at https://jira.lunatech.com/jira/browse/FOO-23
# ...The usual git commit message follows...
Note: While it is slightly inconvenient to start the JIRA line with a comment, it is necessary because it allows you to cancel the commit by exiting without saving. If we had started the commit file with a non-commented line, git would still commit the file if you left the commit message unedited because it would contain a non-commented line. This is not what users expect, so you have to manually uncomment the JIRA line on every commit if you want to keep it in the commit message, but this is quite acceptable.
You can override the start line of the commit messages with the jira.commit.template config:
# Run this INSIDE your project (or make it --global if you prefer)
$ git config jira.commit.template '%i: %t'
The default template is [%i]: %t but you can set it to anything, and %i will be replaced with the issue key, and %t with the issue title.
If the hook fails to connect to JIRA, or the issue does not exist or if you forgot to configure the hook with git config, you will get a comment in the commit file warning you about it.
If the branch name does not match the JIRA key grammar, we will not even try to look it up in JIRA, saving time for master commits.
If the JIRA issue can be resolved from JIRA, it will be cached in .git/jira.cache so that future commits on this branch are faster.
Note: the branch name argument is optional, it will default to the current branch if missing.
$ git jirafix FOO-23
This will do the following:
- Switch to the branch called FOO-23
- Rebase the branch on master
- Switch to the master branch
- Merge the FOO-23 branch on master
- Mark the FOO-23 issue as Fixed
- Add a comment to FOO-23 saying you committed a fix