Jira is a popular issue tracking product commonly used to facilitate agile software development. It comes with support for Atlassian’s own source control, BitBucket, which links issues directly to commits, but you can enable the same support for Gitlab as well.
What Does The Integration Do?
Basically, the Jira integration for Gitlab allows you to link Jira issues to Git commits. Whenever changes are pushed to Gitlab, it will check if any Jira issues are mentioned in the commit message or description, and add a comment to the issue.
This is a simple feature, but it’s crucial for linking the two platforms together. Let’s say you give a developer a set of issues to work on in a code sprint. That developer creates a bunch of commits and pushes them to Gitlab whenever tasks are complete, mentioning issues in the process. When the project manager goes through Jira, they’ll be able to quickly see the related commits for any issues, since there will be links to each commit on the issue.
This works the other way as well—from Gitlab, you’ll be able to quickly see which issues a commit mentions. This mostly just saves you a click, but it’s a nice feature to have when you’ve got a lot of issues.
With the integration, you can also automate the closing of issues from commit messages. If you require developers to move issues from “In Progress” to “In Review,” you can configure Gitlab to do so whenever someone writes ” Resolves PROJECT-1 ” in a commit message.
The same features are also supported for merge requests, useful for when you have a developer working on their own branch that needs merging into master.
Setting Up The Jira Integration
The Jira integration is configured per-project, so head over to your project page and click “Settings” > “Integrations”:
Scroll down in the list of “Project Services” to find and click on “Jira.” You’ll have to configure a bunch of stuff here.
First off, you’ll want to enable the integration in the first place by checking “Active.” You can also toggle off the commit and merge request triggers, but you probably want those.
Next up, put in your Jira web url. If you’re using Jira’s managed cloud version (on atlassian.net), you’ll put in your companyname.atlassian.net URL. If you’re self hosting Jira, you’ll put in the URL to your instance, probably something like jira.companyname.com. Optionally, if you’re self hosting Jira, and put the API on a different domain, you’ll want to enter that here.
If you’re using Jira’s cloud version, you’ll want to put in your email and an API token, which you can get from this page. Create a new token, and paste it in to the box in Gitlab. This will authenticate Gitlab to your Atlassian account. If you’re using self hosted Jira, you’ll simply want to put in your username and password.
Either way, you’ll likely want to make a service account so that messages will show up from “Gitlab” rather than your personal user account. If you don’t want to pay for an extra account, your personal one will work fine.
Next up, you’ll need to give Gitlab a list of transition IDs. These define the different stages of issues, for example, “Todo”, “In Progress”, and “Done”. It’s strange that Gitlab doesn’t automatically configure this, but you can get a list of them from the Jira API by going to the following URL in your browser:
https://yourcompany.atlassian.net/rest/api/2/issue/ISSUE-1/transitions
Note that you will need to substitute “yourcompany” for your actual Jira URL, and sub in “ISSUE-1” for a real issue ID. This will give
var x = `paste response here`
console.log(JSON.parse(x).transitions.map((d)=>d.id).join(‘,’))
Which will return something like 11, 21, 31 (the default) which you will enter into Transition ID box.
Using The Jira Integration
Usage of the Jira integration is pretty simple. There are no boxes to check or levers to pull, simply mention a Jira issue ID anywhere in a commit’s subject or description, and Gitlab will automatically post a comment on the issue linking back to the commit page:
This is nice and all, but being able to close issues from commits is even better. There are currently three trigger words you’ll can to use to close an issue:
- Resolves PROJECT-1
- Closes PROJECT-1
- Fixes PROJECT-1
You can write these inline in commit messages or descriptions:
Each one of them will do the same thing—move the related issue to the last transition ID you specified in the list. If you don’t want developers moving issues directly to “Done,” you can configure Gitlab to send commits to “In Review” instead by leaving out the transition IDs for the unwanted categories.