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.

Set up JIRA to allow API access

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 the JIRA CLI API

Download it (the “Download Binary” link at the bottom), and save it somewhere appropriate on your system.

Set up the git/JIRA integration

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 

Install the JIRA prepare-commit-msg hook

Download the custom hook and install it in your project at .git/hooks/prepare-commit-msg.

Install the custom git/JIRA commands

Download git-jirabranch and git-jirafix and put them somewhere on your path, so that git picks them up as git extensions.

Start having fun

Create an issue branch

$ git jirabranch FOO-23 

This will do the following:

1. Create a branch called FOO-23
2. Switch to the new branch
3. Mark the FOO-23 issue as in progress
4. Add a comment to FOO-23 saying you started working on it

Work

$ 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.

Customising the pre-filled commit message

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.

What happens if?

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.

Merge the branch back to master when you have fixed the issue

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:

1. Switch to the branch called FOO-23
2. Rebase the branch on master
3. Switch to the master branch
4. Merge the FOO-23 branch on master
5. Mark the FOO-23 issue as Fixed
6. Add a comment to FOO-23 saying you committed a fix