Integrating Jira with GitLab
This doc was part of an EAP of the DVCS Connector. Features described here have been officially released in Jira 8.14. See Linking a GitLab repository with Jira.
This guide will help you create the integration between Jira and GitLab, and then use GitLab as an account in the DVCS Connector. To create the integration, we'll use the OAuth 2.0 library that's available in Jira 8.10 and later, and Jira 8.5. This will help us get around the limited OAuth 2.0 functionality available in the GitHub implementation, and also let us use a standard feature across Jira and other Atlassian products.
Good to know: API usage
When calling the GitLab API, we use keyset pagination set to a page size of 100 by default. If you'd like to change that, you can do it by using the following system property, but bear in mind that the value must be between 20-100. For more info, see Keyset based pagination.
Required Jira version
The OAuth 2.0 integration that we'll be using is available in Jira 8.10 and later, and Jira 8.5.9 and later. You'll need one of these versions to be able to create the integration.
If you're using GitLab Cloud, you'll need to set the following system property so that GitLab accepts our OAuth 2.0 connection.
Creating the OAuth 2.0 integration
Here are the steps needed to integrate Jira with GitLab.
GitLab OAuth 2.0 setup
You'll start by adding a new application in GitLab. This will allow you to set the right scopes, and get the GitLab Application ID and Secret, which are needed in Jira.
Which user to use?
You'll be adding an application in GitLab through user settings. You'll need to use a user that has access to all repositories you want to have in the DVCS Connector. You can also use the System Application but this account has access to all repositories in the system.
- In GitLab, go to User Settings > Applications, and add a new application. Use the following data:
- Redirect URI: Enter a placeholder URI. You'll later replace it with the one you get from Jira.
- Scopes: Select
api. This is required for the DVCS connection to work.
- After creating the application, you'll get the Application ID and Application Secret, which we'll use in the Jira OAuth 2.0 configuration.
For more info on adding a new application in GitLab, see:
Jira OAuth 2.0 setup
Once you have the Application ID and Secret from GitLab, you can create the OAuth 2.0 integration in Jira.
- Go to Administration > OAuth 2.0 integration.
- Create the integration with the following data:
- Client ID: GitLab Application ID
- Client secret: GitLab Secret
- Authorization Endpoint:
- Authorization token:
- Copy the Redirect URL and go back to your GitLab OAuth configuration created earlier. Change your placeholder URI to this one.
For more info on creating the OAuth 2.0 integration in Jira, see Integrating with OAuth 2.0.
Sample OAuth 2.0 integration in Jira
Choosing GitLab as an account in DVCS
Once the OAuth 2.0 is created, you can select it from the drop-down list when creating the GitLab integration in the DVCS Connector. The Team or User Account will be the unique name of the integration and the Host URL will be the url of the gitlab instance (either https://gitlab.com for cloud, or the external url of your gitlab enterprise instance).
When you select GitLab as an account, we'll verify that it includes the required scopes of
api by using this system property:
dvcs.connector.gitlab.required.scopes=api sudo read_registry
Just in case GitLab changes something on their side or you'd like to verify additional scopes, you can use this system property with a whitespace-delimited list of scopes.