Integrating Jira and GitLab is one of the best ways for software teams to streamline their workflows and improve team collaboration. GitLab and Jira are two of the most popular tools available for tracking projects and development work. GitLab is primarily a hosting service that allows development teams to store their code. GitLab saw its first commit made in 2011 and has grown to over 30 million registered users in 2021. Jira launched in 2002 and is one of the most used project management tools with over 190,000 customers. 

While engineers and developers generally spend more time in GitLab, less technical stakeholders often rely on Jira for status updates. In this article, we’ll show you how to set up a Jira GitLab integration so Jira users can see commits, pull requests, branches, and more. With GitLab and Jira integrated together, you’ll be able to manage your projects more efficiently and provide greater project visibility to key stakeholders.

A key part of this is understanding how to link issues/tasks/bugs to the source code in your Git repositories. This linkage is crucial for ensuring traceability and transparency of code changes vis-a-vis tasks assigned to developers.

One of the easiest ways to integrate GitLab and Jira is with Git Integration for Jira. Built by GitKraken, this top Atlassian marketplace app can be deployed on Jira Cloud, Server, and Data Center. It also supports integrations with GitLab in the cloud (GitLab.com) or on your own infrastructure (GitLab self-managed). 

Integrating GitLab with Jira

• Connect GitLab with Jira
• Link GitLab with Jira Issues
• Create GitLab Branch in Jira
• Create GitLab Pull Request in Jira
• Configure Jira GitLab Webhooks
• GitLab Jira Integration Benefits

Connect GitLab with Jira

We recommend creating a GitLab user specifically for the integration. This way, the GitLab user can have defined permissions to perform given tasks. Ensure this user has access to the repositories that you wish to integrate with Jira. The first step of the integration is to create a Personal Access Token that will be used to authenticate when creating the GitLab Jira integration. 

Steps to Create a Personal Access Token in GitLab

1. Log in to GitLab (e.g. GitLab.com)
2. On the top right select your user profile and then Preferences
3. On the left side, select Access Tokens
4. Enter the token name and when you want the token to expire (set this far enough into the future to ensure the integration does not break)
5. Under select scopes, select api, read_api, read_repository and write_repository
6. Select Create personal access token
7. The page will update – copy the value under Your new personal access token

To continue your GitLab Jira integration, you’ll need to install Git Integration for Jira from the Atlassian marketplace. Like all Atlassian marketplace apps, you’ll need a Jira administrator to install the app. Once you have Git Integration for Jira installed, you can begin connecting your GitLab repositories with the associated Jira projects. 

1. From the top navigation bar in Jira, select Apps and then Git Integration: Manage integrations
2. Select Add Integration button on the top right
3. From the Select Git hosting service page, select GitLab.com for cloud or GitLab Server for self-hosted
4. Enter the Personal Access Token that you created earlier and then select the Connect and select repositories button
5. Select the GitLab repositories you wish to integrate with Jira and then click the Connect repositories button

At this point, the app will index your repositories and make them available to be viewed in Jira.

Linking GitLab with Jira Issues

To create a link between a Git commit and a Jira issue, developers must include the Jira issue key in their commit message. 

Example Git commit message: GIT-4322 – Updated the plugin …

In this case, GIT-4322 is the Jira issue key linking the commit message to the Jira issue. Commits that are part of non-main branches will be included only if the main branch doesn’t have them.

As a best practice when working with a sub-task, put the parent and sub-task Jira issue keys in the commit message so that the commit shows in both places. This way, the commit for the sub-task does not get lost in the many commits of the parent issue.

Create GitLab Branch in Jira

On your Jira Cloud instance, open a Jira issue. On the Jira Git integration development panel, click Open Git integration then click Create branch. This will open a dialog box where the branch can be created.

1. Select a Repository from the list.
   • The git host service logo is displayed for all the repositories in the dropdown list to easily identify which git service they belong to.
   • If there are several repositories with the same name, the listed GitLab repositories will have their names attached with a GitLab owner name. For example, johnsmith/second-webhook-test-repo.
   • Use the search box in the dropdown list to filter displayed repositories.
   • *Optional- Designate the repository to be the default selected repository for current Jira project. 
2. Choose a Source branch.
   • *Optional- Designate the branch to be the default selected branch for the currently selected repository.
3. Enter a Branch name or leave it as is (recommended).
4. Click Create branch to complete this process.

The newly-created branch is now associated with that Jira issue listed in the development panel under Branches. Perform a commit to the newly-created branch to be ready for merge.

Create GitLab Pull Request in Jira

To create a pull request from a Jira issue, open the desired Jira issue, select the Jira Git integration development panel, click Open Git integration then click Create pull request. This will open a dialog box where the merge request can be made.

1. Select a Repository from the list.
   • The Git host service logo is displayed for all the repositories in the dropdown list to easily identify which git service they belong to.
   • If there are several repositories with the same name, the listed GitLab repositories will have their names attached with a GitLab group name. For example, BigBrassBand/second-webhook-test-repo.
   • Use the search box in the dropdown list to filter displayed repositories.
   • *Optional- Designate the repository to be the default selected repository for current Jira project. 
2. Choose the newly-created branch as the Source branch.
   • *Optional- Designate the branch to be the default selected branch for the currently selected repository.
3. Set main as the Target branch.
4. Enter a descriptive Title or leave it as is (recommended).
5. Click Create pull request to complete this process. Follow the link to the PR to setup for review and approval.

Merge requests are still indexed based on branch name even if the MR title does not have the Jira issue key – as long as the branch name contains the Jira issue key. Preview allows you to see the comparison view of the current changes in the selected Source branch vs Target branch (usually main).

Jira GitLab Webhooks

By default, repositories are reindexed on a fixed interval. If you want Jira to reflect GitLab updates in real time, you must set up Webhooks. To add webhooks to your connected GitLab repositories, complete the following steps.

1. In Jira, select Apps from the top navigation bar and then Git Integration: Manage integrations
2. Select the GitLab integration you wish to add webhooks to
3. On the left, select Feature Settings
4. Copy the URL under Indexing triggers

Next, we’ll need to go to GitLab to finish the integration.

1. In GitLab, from your project select Settings and then Webhooks
2. Paste in the URL you copied previously
3. Under Trigger, select Push events, merge request events, and Enable SSL verification
4. Select Add webhook

Your webhook is now created. Commits, branches, and merge requests that are associated with a Jira issue will now be visible in Jira issues in real time.

Jira GitLab Integration Benefits

Integrating GitLab with Jira is beneficial for individual developers and key stakeholders. By bridging the gap between DevOps and project management tools, team members stay more informed and efficient.

Top Benefits For Developers

• Less administrative work: Use Smart Commits and Jira automation to keep Jira updated so you don’t need to change your workflows—and spend way less time in Jira.
• Fewer ad-hoc status updates: Development stakeholders know when you create a branch, make a commit, and then a pull request. Give them the visibility they want without adding more work for you.
• Less context switching: Stay in your flow, and focus on coding. If you have to go into Jira, links to your repo hosting providers make it easy to transition.  

Top Benefits For Project and Product Managers

• More visibility: Development activity doesn’t need to be a black hole in Jira. Easily understand what’s happening in your Git repos with contextual data presented alongside Jira issues and projects.
• A Cleaner Jira: Reduce the need for developers to manually update Jira issues. Leverage Jira automation and Smart Commits to transition issue status, assignees, and more, all without manual intervention.
• Better planning and warning systems: Issue closed without a commit and merge? Easily flag issues that should have activity but don’t.