This is the second in a series of posts on GitLab Jira integration strategies. The first post explains how to integrate GitLab.com with Jira Cloud.

The advantages of a GitLab Jira integration are clear:

Here's everything you need to know to achieve a GitLab Jira integration.

Pre-Configuration

As you approach configuring your GitLab project to Jira, you can choose from two options that best fit your organization's needs. You can either:

It should be noted that each GitLab project can be configured to connect to an entire Jira instance. That means one GitLab project can interact with all Jira projects in that instance, once configured. Therefore, you will not have to explicitly associate a GitLab project with any single Jira project.

GitLab offers several different options that allow you to integrate Jira in a way that best fits you and your organization's needs based on how you’ve set up your Jira software. Let’s take a deeper look into how to set-up each of these available options.

Configuring Jira

The first step in setting up your Gitlab Jira integration is having your Jira configuration in order.

Jira Server Jira Server supports basic authentication. When connecting, a username and password are required. Note that connecting to Jira Server via CAS is not possible. Set up a user in Jira Server first and then proceed to Configuring GitLab.

Jira Cloud Jira Cloud supports authentication through an API token, and in order to begin the process you need to start by creating one within Jira. When connecting to Jira Cloud, an email and API token are required. Set up a user in Jira Cloud first and then proceed to Configuring GitLab.

Create an API token here: https://id.atlassian.com/manage-profile/security/api-tokens

Create API Token in Jira Jira API token creation

Copy API Token Jira API token copy to clipboard

Configuring GitLab

As mentioned above, you can begin setting up the Jira integration either by using a service template that defaults all GitLab projects to pre-fill Jira values or you can set up at an individual project level.

To set up a service template:

GitLab Service Templates GitLab Service Templates

2a. For each project, you will still need to configure the issue tracking URLs by replacing :issues_tracker_id in the above screenshot with the ID used by your external issue tracker.

Issue Tracker ID Issue Tracker ID

To set up a individual project template:

Enable Jira Integration Enable Jira Integration

Select Trigger Action Select Trigger Action

Field Description
Web URL The base URL to the Jira instance web interface which is being linked to this GitLab project. E.g., https://jira.example.com.
Jira API URL The base URL to the Jira instance API. Web URL value will be used if not set. E.g., https://jira-api.example.com. Leave this field blank (or use the same value of Web URL) if using Jira Cloud.
Username or Email Use username for Jira Server or email for Jira Cloud
Transition ID Required for closing Jira issues via commits or merge requests. This is the ID of a transition in Jira that moves issues to a desired state. If you insert multiple transition IDs separated by , or;, the issue is moved to each state, one after another, using the given order. (See below for obtaining a transition ID)

In order to obtain a transition ID, do the following:

Note: The transition ID may vary between workflows (e.g., bug vs. story), even if the status you are changing to is the same.

Transition ID Transition ID

Your GitLab project can now interact with all Jira projects in your instance and the project now displays a Jira link that opens the Jira project.

When you have configured all settings, click Test settings and save changes.

Test settings and save changes Test settings and save changes

It should be noted that you can only display issues from a single Jira project within a given GitLab project.

The integration is now activated:

Active Jira Integration Active Jira Integration

Jira Issues

By now you should have configured Jira and enabled the Jira service in GitLab. If everything is set up correctly you should be able to reference and close Jira issues by just mentioning their ID in GitLab commits and merge requests.

Jira issue IDs must be formatted in uppercase for the integration to work.

1.Reference Jira issues

When GitLab project has Jira issue tracker configured and enabled, mentioning Jira issue in GitLab will automatically add a comment in Jira issue with the link back to GitLab. This means that in comments in merge requests and commits referencing an issue, e.g., PROJECT-7, will add a comment in Jira issue in the format:

USER mentioned this issue in RESOURCE_NAME of [PROJECT_NAME|LINK_TO_COMMENT]: ENTITY_TITLE

Reference Jira issues Reference Jira issues

For example, the following commit will reference the Jira issue with PROJECT-1 as its ID:

git commit -m "PROJECT-1 Fix spelling and grammar"

Closing Jira Issues

Jira issues can be closed directly from GitLab by using trigger words in commits and merge requests. When a commit which contains the trigger word followed by the Jira issue ID in the commit message is pushed, GitLab will add a comment in the mentioned Jira issue and immediately close it (provided the transition ID was set up correctly).

There are currently three trigger words, and you can use either one to achieve the same goal:

where PROJECT-1 is the ID of the Jira issue.

Notes:

Let’s consider the following example:

In the following screenshot you can see what the link references to the Jira issue look like.

GitLab link references GitLab link references

Once this merge request is merged, the Jira issue will be automatically closed with a link to the commit that resolved the issue.

Jira Issue auto closes when GitLab MR merges Jira Issue auto closes when GitLab MR merges

Development Panel Integration Set-Up

A. Jira DVCS configuration

When using the Jira DVCS configuration, there are several different configurations you can make that are dependent on how your Jira/GitLab instances are managed.

B. GitLab account configuration for DVCS

Admin Creates Integration Admin Creates Integration

Tip: To ensure that regular user account maintenance doesn’t impact your integration, create and use a single-purpose jira user in GitLab.

Jira DVCS Connector setup

Note: If you’re using GitLab.com and Jira Cloud, we recommend you use the GitLab for Jira app, unless you have a specific need for the DVCS Connector.

Check api in Applications Check api in Applications

Application was created successfuly Application was created successfuly

Go to DVCS in Settings Go to DVCS in Settings

Click Link to start new integration Click Link to start new integration

Add new account Add new account

In the Host URL field, enter https:///, replacing with your GitLab instance domain. For example, if you are using GitLab.com, this would be https://gitlab.com/.

*Note: If using a GitLab version earlier than 11.3 the Host URL value should be https:///-/jira*

For the Client ID field, use the Application ID value from the previous section.

For the Client Secret field, use the Secret value from the previous section.

Ensure that the rest of the checkboxes are checked.

In the future, we plan on implementing real-time integration. If you need to refresh the data manually, you can do this from the Applications -> DVCS accounts screen where you initially set up the integration:

Refresh data manually Refresh data manually

To connect additional GitLab projects from other GitLab top-level groups (or personal namespaces), repeat the previous steps with additional Jira DVCS accounts.

For troubleshooting your DVCS connection, go to GitLab Docs for more information.

In our next blog post we'll look at Usage.

Cover image by Mikołaj Idziak on Unsplash.

Try all GitLab features - free for 30 days

GitLab is more than just source code management or CI/CD. It is a full software development lifecycle & DevOps tool in a single application.

Try GitLab Free
Git is a trademark of Software Freedom Conservancy and our use of 'GitLab' is under license

Try GitLab risk-free for 30 days.

No credit card required. Have questions? Contact us.

Gitlab x icon svg