Linking GitLab accounts

You can link your GitLab and GitLab Enterprise accounts and their repositories to Jira, and see the development information from pull requests displayed in your issues.

Supported versions

Here’s a list of supported versions:

Prerequisite: Integrate Jira with GitLab using OAuth 2.0

Before you can add your GitLab account to the accounts page, you need to integrate Jira with GitLab using OAuth 2.0.

In Jira

To add a new OAuth 2.0 integration in Jira:

1. In the upper-right corner of the screen, select Administration  > System.

2. In the sidebar, select OAuth 2.0 and then select Add new integration.

3. In Service provider, select Custom.

4. Enter your integration’s name.

5. Don’t worry about the Client ID and Client Secret right now. You’ll get them from GitLab in the next steps.

6. Enter the authorization and token endpoint, as shown in the table below.

   GitLab type	Authorization endpoint	Token endpoint
   GitLab.com	https://gitlab.com/oauth/authorize	https://gitlab.com/oauth/token
   GitLab self-managed	<GITLAB_SELF_MANAGED_URL>/oauth/authorize	<GITLAB_SELF_MANAGED_URL>/oauth/token

7. Copy the Redirect URL. You’ll use it in GitLab in the next step. 

In GitLab

Leave your Jira configuration open and move to GitLab to create a new application. This will give you Application ID and Application Secret that you’ll use in Jira.

1. In GitLab, go to User Settings > Applications, and add a new application. Use the following data:

   • Redirect URI: Enter the URL you copied from Jira.

   • Confidential: Keep that enabled.

   • Scopes: Select api. This is required for the connection to work.

   
2. After creating the application, you should get the Application ID and Application Secret, like on the image below.

In Jira again

Go back to your configuration in Jira, and enter the missing information to complete the integration.

1. Enter GitLab’s Application ID as Client ID.

2. Enter GitLab’s Application Secret as Client Secret.

3. In Scopes, select api.

4. Save the integration, and then select Test Connection. 

5. In the GitLab authorization prompt, select Authorize.

Link your GitLab account

With the OAuth 2.0 integration created, you can use it when linking your GitLab account on the accounts page in Jira:

1. In the upper-right corner of the screen, select Administration  > Applications.

2. Under Intergations, select DVCS Accounts.
3. Select Link an account.

4. In the Host dropdown, select GitLab or GitLab Self-Managed.

   • For GitLab Self-Managed, enter your GitLab Host URL.

   • For Gitlab, the Host URL is fixed to https://gitlab.com.
     
     

5. In the Team or User Account, enter the target group and optional subgroups. 

   Requirements for entering groups and subgroups...

   • Groups must be entered as groupA/sub-groupA/sub-sub-groupA. 

     You can only have one group active as a configuration at one time. For example:

     • If an existing integration is already using groupA, you won't be able to use groupA/sub-groupA in your new integration.

     • Likewise, if an existing integration is using groupA/sub-groupA, you won't be able to use groupA in your new integration.

   • All spaces must be changed to dashes (-). For example, a group My projects needs to be my-projects. This also applies to subgroups: My Projects > More Projects would be my-projects/more-projects. Another way to get this right is to access your group on Gitlab, and copy the URL, for example http://gitlab.com/my-projects/more-projects.

6. In the Client Configuration, select the created OAuth 2.0 integration. If you have only one, it will be automatically selected.
7. Select Add. 

What’s next?

Here’s what happens after adding your account:

• Syncing repositories: Your account appears on the page and Jira starts syncing its repositories, if you decided to link them automatically. For details, see Integrating dev tools using .

• Matching issues: If your commits and pull requests include issue keys, Jira will try to find them and add the relevant information to your issues. For details, see Referencing issues in your development work.

• Displaying dev info: If referenced correctly, the dev information will be added to your issues to give everyone involved more context. For details, see Viewing the dev info for an issue.

• Workflow triggers: One of the benefits of integrating your development tools is adding workflow triggers that, for example, lets you change the issue status after you create a new branch. For details, see Configuring workflow triggers.