GitLab CE/EE

Integrate GitLab CE/EE with Jira Data Center/Server

Introduced in v2.9.4 of the Git Integration for Jira app, this feature tracks added or deleted repositories from a remote GitLab server (EE/CE) and automatically imports those Git repository references into Jira.

GitLab v10+ stopped accepting username/password credentials for API access and will only recognize Personal Access Tokens (PAT) and OAuth authentications. Service users are strongly advised to switch from using username/password for newer versions of GitLab Server (CE/EE) to using PAT.

For GitLab Server service users, they won’t see the issue until they upgrade their GitLab Servers to version 10 and higher. Git Integration for Jira app offers pre-v10 GitLab Server service users as a Legacy connection option.

Quickly learn how to connect GitLab CE/EE git repositories via Git Integration for Jira Server app.

What’s on this page:

• Integrate GitLab CE/EE with Jira Data Center/Server
  • Permissions
  • Creating a personal access token
  • Using Full feature integration
  • Single repository (Manual integration)
  • Post-install tips
  • Setting up GitLab web links
  • Viewing git commits in Jira Server
  • Working with branches and merge requests
  • Default branch
  • Creating branches
  • Merge request
  • More Integration Guides

Permissions

GitLab can have users with different access level to a group or project. If the user’s connected GitLab repositories to Jira are not accessible or commits are not showing for that user — it’s related to permission issues. This can be a per user, repository or a project level restriction.

If you encounter access permission issues, you will need to ask your Git administrator to grant you the required level of access to specific projects. If you are a Git administrator, you will need to setup a GitLab user with the minimum required permissions to view GitLab projects from Jira.

Take the following cases for example:

• The personal access token (PAT) that the GitLab user provided doesn’t have the correct permissions within GitLab to view source code for specific repositories.

• The GitLab user doesn’t have access privileges to a GitLab repository or is not a member of a group that has access to specific repositories.

We recommend creating a specific GitLab user for the integration. This way, the GitLab user can have specific permissions to do the given tasks.

For minimum access (read-only) permissions:

1. Set the user account profile’s PAT scope to read_repository.

2. The GitLab user is set to only read a specific repository.  Set to Reporter role.

This level of access allows the user to view commits for the specific repository.

For users who will be tasked with creating branches and merge requests:

1. Set the user account profile’s PAT scope to api.

2. The GitLab user should be set to read/write access for the specific repository.  Set to Developer role.

This level of access allows the user to create/delete branches and create merge requests.

For more information, see GitLab Permissions ».

Creating a personal access token

GitLab Server version 10.2 and newer requires a configured PAT. Follow this article for some specific instructions on how to create PAT for Jira git integration.

Using Full feature integration

This process requires an existing GitLab Server EE or GitLab Server CE. If your GitLab Server version is 10.2 and newer, a personal access token must be configured.

We recommend using the Add new integration panel to connect multiple repositories from your GitLab CE/EE account. This setup uses full feature integration offering functions and features not found on single repository connections.

1. On the Jira Server dashboard menu, go to Git ➜ Manage repositories.

2. The git configuration page for connecting repositories is displayed.

3. On the Add new integration panel, click GitLab1. The following screen is displayed.

   
   

   • For the External service, select GitLab Server (CE/EE) since it uses the new GitLab API v4 format. Support for GitLab API v3 is deprecated.

   • Enter the Host URL of the GitLab server.

   • Enter the username and PAT credentials for server authentication. 2FA must be enabled in your GitLab Server and PAT has been configured.

   • Configuring the Advanced settings is optional. However, admins/power users may set how the project listing is displayed.

     
     

     • Custom API Path  –  this is a relative path that starts with “/”. The integration will use the relative REST API path to retrieve the list of tracked repositories. The maximum allowed length is 2000 characters or less. For more information on GitLab custom API paths, see GitLab API. For more GitLab CE/EE examples, see article Jira Server: Working with Custom API Path.

       GitLab version API support:
       ---------------------------
       Gitlab v9.5 and above -- only API v4
       Gitlab v9.0 to v9.4.x -- API v4 or API v3 (API v3 unsupported)

     • JMESPath Filter  –  JMESPath is a query language for JSON used to filter API results and to limit which repositories are integrated. The maximum allowed length is 2000 characters or less. Read about JMESPath expressions on their website.

       For help with writing expressions, please contact support. To learn more GitLab CE/EE examples, see article Working with JMESPath Filters.

     • Fetch refspec  –  Git refspecs contains patterns mapped as references from the remote to the local repository.
       For more information, see Git Internals — The Refspec.

       • The first two refspec options are required.

       • The rest of the options are OPTIONAL:

         • Clone and index ref notes (refs/notes) – This is a reference to refs/notes/* used for fetching. This option is enabled by default. This affects git notes which are not shown:

           • …when refs/notes are disabled on connecting a repository.

           • …when a new note comes when refs/notes is disabled.

         • Clone and index changes (refs/changes) – This is a reference to refs/changes/* used for fetching. This option is turned off by default.

         • Clone and index other refs – This is a user-defined list of references used for fetching. It is a comma-separated list with the format:

           • +refs/refname1/*:refs/refname1/*, refs/refname2/*:refs/refname2/*, …

   While Custom API Path and JMESPath filter are mutually exclusive, you can use one, the other, both or neither.

4. Click Connect. The Git Integration for Jira app will detect GitLab CE/EE repositories.

   • Currently, the Git Integration for Jira app scans only the repositories visible to the user which is used for scanning. The repositories which are publicly visible (shared for all members or visible to the member with the admin rights) will not be scanned. This will be supported in a future release.

   • On the first connection of this integration, the first 30 repositories are displayed in the list for import. The entire repository list can be viewed via Manage repositories ➜   Actions ➜ Show integration repositories.

5. Click Import repositories to start the integration process. The Settings screen is displayed.

   
   

   • For the Integration Settings, setting the Require User PAT option to ON, will require users to provide PAT specific for branch and merge requests (via the developer panel on the Jira issue page). For more information on this feature, see Integration Settings: Require User PAT.

   • Set Smart Commits and Repository Browser to enable/disable these features.

   • Set Project Permissions according to your organization’s project association rules. For detailed information, see Associating project permissions.

6. Click Finish to complete this setup.

GitLab CE/EE repositories are now connected to Jira Server.

The GitLab server is added to the repositories list as a connected server and is automatically reindexed.

Manage repositories of a connected GitLab server via the Manage Git integration for Jira repositories list under  Actions ➜ Show integration repositories to modify tracked repositories settings.

Repositories added or removed from GitLab server will be likewise added or removed from Jira Server.

Single repository (Manual integration)

This process requires an existing GitLab CE/EE git repository. Look for the GitLab repository URL on the repository project page.

Choose between SSH or HTTPS. Use this information to connect the GitLab git repository to your Jira server via Git Integration for Jira app:

1. On your Jira dashboard menu, go to Git ➜ Manage repositories.

2. Click Connect to Git Repository (or the Git icon on the Add new integration panel) to open the Connect Wizard.

3. Paste the URL from GitLab CE/EE repository page in the provided box.

4. Continue to the next step by following the screen instructions.

5. Click Finish to complete this process.

The repository is now connected to Jira Server.

Post-install tips

We recommend to change the following setting if there are connection issues:

Go to the general settings in Git Integration app configuration page (Git ➜ Manage repositories ➜ (sidebar) General settings) then set the Git operation timeout to 120 or 180. Dafault value is 60.

Setting up GitLab web links

The Git Integration for Jira app automatically configures web linking for GitLab CE/EE git repositories.

For single repository connections, web link setup is optional. However, git links will become available in Git Commits tab when configured.

For more information on this feature, see Documentation: Web linking.

Viewing git commits in Jira Server

1. Perform a git commit by adding the Jira issue key in the commit message. This will associate the commit to the mentioned Jira issue.

2. Open the Jira issue.

3. Scroll down to the Activity panel then click the Git Commits tab.

4. Click View Full Commit to view the code diff.

For more information about this feature, see Documentation: Linking git commits to Jira issues.

Working with branches and merge requests

For this feature to work with GitLab CE/EE, the user must have the Write permissions and the api PAT scope.

Default branch

Most git integrations allow changing of the default branch of the repository/project other than “master”. This change is reflected in the Repository Settings of the Git Integration for Jira app on the next reindex. Full feature integrations support this feature where Git Integration for Jira app gets the default branch from almost all integrations and apply this setting at repository level.

Creating branches

On your Jira Server, open a Jira issue.

1. On the Jira developer panel under Git integration, click Create branch. The following dialog is displayed.

   
   

   • Select a Repository from the list.
     If there are several repositories with the same name, the listed GitLab CE/EE repositories will have their names attached with a GitLab owner name. For example, johnsmith/second-webhook-test-repo.

   • Choose a Base branch.

   • Enter a Branch name or leave it as is (recommended).

   • If the Require User PAT option is enabled in the Integration Settings and a user PAT isn’t configured yet for the selected repository via Repository Browser, the following dialog is displayed instead:

     
     

   • Click the link label to setup the PAT. The following dialog appears.

     
     

     • Enter your personal access token from your GitLab profile settings.

     • When you click Update to save the settings:

       • If this field is blank and no PAT is provided, nothing is changed and saved.

       • If PAT has been previously configured and this field is blank, the PAT will be discarded.

       • If a PAT has changed since last configuration and is provided, the new PAT is used.

     • PAT settings can be accessed via Repository browser ➜ Pers. access column.

       
       

     • Click the Edit   icon to setup/reconfigure PAT. The checkmark adjacent to the edit icon indicates PAT has been configured.

2. Click Create branch. The newly-created branch is now listed in the developer panel under Branches.

Perform a commit to the newly-created branch to be ready for merge.

Merge request

The merge request feature works the same as pull request.

To create a merge request and merge it to the main source (master):

1. On your Jira Server, open the Jira issue where your previously created a branch.

2. On the developer panel under Git integration, click Create merge request. The following dialog is displayed.

   
   

   • Select a Repository from the list.
     If there are several repositories with the same name, the listed GitLab CE/EE repositories will have their names attached with a GitLab owner name. For example, johnsmith/second-webhook-test-repo.

   • Choose the newly-created branch as the Source branch.

   • Set master as the Target branch.

   • Enter a descriptive title or leave it as is (recommended).

   • If the Require User PAT option is enabled in the Integration Settings and a user PAT isn’t configured yet for the selected repository via Repository Browser, the following dialog is displayed instead.

     
     

     • If an invalid PAT was configured for the selected repository, the merge request creation process will fail.

3. Click Create to create the merge request.

The merge request is listed on the developer panel of the Jira issue page.

The merge request is also ready for approval by the reviewers in your GitLab web portal.

More Integration Guides

GitHub.com (Git Integration for Jira Data Center/Server)

GitHub Enterprise Server (Git Integration for Jira Data Center/Server)

GitHub App integration (Git Integration for Jira Data Center/Server)

GitLab.com (Git Integration for Jira Data Center/Server)

GitLab CE/EE (this page)

Azure DevOps | Visual Studio Team Services (VSTS) (Git Integration for Data Center/Jira Server)

Azure DevOps Server | Team Foundation Services (TFS) (Git Integration for Jira Data Center/Server)

AWS CodeCommit (Git Integration for Jira Data Center/Server)

Gerrit (Git Integration for Jira Data Center/Server)

Bitbucket Server (Git Integration for Jira Data Center/Server)

Bonobo (Git Integration for Jira Data Center/Server)

Windows Network | Server Share (Git Integration for Jira Data Center/Server)

Tracked Folders (Git Integration for Jira Data Center/Server)

Back to: Integration basics (Git Integration for Jira Data Center/Server)