Skip to main content

Setting up the GitLab and Jira DVCS connector

Objective

Understand the mechanics behind the GitLab and Jira connector and how to set it up.

How to set the connector up

Please read this article for a refresher on how you can connect Jira Software to compatible development tools like GitLab.

How the connector works

Review the "How it works" section for details on DVCS.

Connecting Jira and GitLab

GitLab support is now an officially supported DVCS account type with support for both the polling and non-polling webhooks.

API usage

When calling the GitLab API, we use keyset pagination set to a page size of 100 by default. The page size can be changed via a system property which at the time of writing has to be between 20 - 100.
1dvcs.connector.gitlab.page.size

OAuth 2

We will be using the OAuth 2 library in new versions of Jira (also backported to 8.5). This will get around the limited OAuth 2 functionality available in the GitHub implementation, and use a standard feature across Jira and other Atlassian products.
Setting up GitLab and Jira DVCS Connector 1

GitLab Cloud

In order for GitLab Cloud to accept the OAuth 2 connection, you must set a system property.
1atlassian.oauth2.client.add.empty.user.agent.for.token.requests

GitLab OAuth 2 setup

This will require the creation of OAuth credentials on the GitLab side, which is supported by both the cloud and enterprise versions. The API scope is required for the DVCS connection to work. When creating this, add a dummy URL in the redirect URI to be replaced later.
Setting up GitLab and Jira DVCS Connector 2
This will provide the Application ID and secret which will be used in the Jira OAuth 2 configuration creation.
Setting up GitLab and Jira DVCS Connector 3

Jira OAuth 2 configuration setup

On the Jira side, we will create the configuration in the OAuth system admin screen <jira-domain>/plugins/servlet/oauth2 under the "Custom" option. Use the GitLab Application ID for the "Client ID" field, GitLab secret for the "Client secret" field, and API for the "Scopes" field.
Setting up GitLab and Jira DVCS Connector 4
The "Authorization endpoint" and "Token endpoint" fields will depend on whether it is GitLab Cloud or on-prem, with cloud being https://gitlab.com/oauth/authorize and https://gitlab.com/oauth/token respectively, while on-prem will be similar but swapping https://gitlab.com for the url of the on-prem service.
Either on this screen before saving, or while accessing the the configuration again via edit, copy the redirect URL and go back to your GitLab OAuth configuration created earlier. Apply the redirect URL to its configuration.
Once the OAuth configuration is setup, it’s a simple case of selecting it in the dropdown list when creating the GitLab integration. The "Team or User Account" will be the directory where the project resides, so for example https://gitlab.com/root in the screenshot below.
Setting up GitLab and Jira DVCS Connector 5
We will carry out a sanity check that the selected GitLab OAuth configuration contains the required scope of API. This can be changed via a system property with a whitespace delimited list of scopes.
1dvcs.connector.gitlab.required.scopes2dvcs.connector.gitlab.required.scopes=api sudo read_registry
This gives you the flexibility to change it if GitLab changes things on their side.

Was this content helpful?

Connect, share, or get additional help

Atlassian Community