GitLab.com

Using Jira Server or Data Center? See the corresponding article.

Integrate GitLab.com with Jira Cloud

GitLab introduced personal access tokens (PAT) since version 8.8 and now (v10+) prefers this type of authentication for accessing the git repositories.  Service users are strongly advised to switch from using username/password to using Personal Access Tokens (PAT) for GitLab.com.

The Git Integration for Jira app supports v3 and v4 of the GitLab API (in both Jira Cloud and Jira Server/Data Center).

Quickly learn how to connect GitLab.com git repositories via Git Integration for Jira Cloud app.

What's on this page:


Right click here and open this video in a new tab/window for more viewing options.

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 permisions 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

If two-factor authentication is enabled for your GitLab account, you will need to create a PAT to access your git repositories. Enable two-factor authentication in your GitLab.com account for increased security.

While instructions from GitHub works just fine, follow this article for a quick step-by-step guide to get you started.

Using Auto-Connect

This process requires an existing GitLab.com account.  Multiple git repositories in a GitLab.com account will be connected via Git Integration for Jira app.

While instructions from GitLab works just fine, here are some specific instructions to get you up and running.

We recommend using the Auto-connect integration panel1 to connect multiple repositories from your GitLab.com account.

  1. On your Jira Cloud dashboard menu, go to AppsGit Integration: Manage Git repositories.

  2. On the Auto-connect integration panel, click GitLab. The following screen is displayed.

    1. The GitLab.com external service is selected by default. Paste the personal access token in the provided field.

    2. 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 maximum allowed length is 2000 characters or less.  The integration will use the relative REST API path to retrieve the list of tracked repositories.
        For more information on GitLab custom API paths, see GitLab API.
        For more examples, see article Jira Cloud: Working with Custom API Path.

        1 2 3 4 5 6 GitLab version API support: Gitlab v8.16 and earlier -- API v3. Gitlab v8.17 to v8.xx -- API v3.  Gitlab v9.0 to v9.4.x -- API v3 and API v4. Gitlab v9.5 and above -- only API v4.
        • Remember:
          The GitLab.com API can see all the public projects. For GitLab.com, we recommend using JMESPath over the Custom API path when possible.

      • 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 examples, see article Jira Cloud: Working with JMESPath Filters.

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

  3. Click Next.

  4. On the following screen, the Git Integration for Jira app will read all available repositories from your GitLab account.

  5. Click Connect.

The GitLab.com git repositories are now connected to Jira Cloud.

There will be a slight delay in adding 2FA-enabled repositories compared to others.  These will show in the git configuration list eventually.

Administrators
If you need to require users PAT for creating branches or merge requests, turn on this setting via the selected integration in Manage Git repositories – Actions > Edit integration settings.

Single Repository

This process requires an existing GitLab git repository.

Look for the 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 Cloud via Git Integration for Jira app.

  1. On your Jira Cloud dashboard menu, go to Apps ➜ Git Integration: Manage Git repositories.

  2. Click Connect to Git Repository to open the Connect Wizard.

  3. Paste the URL from GitLab 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 Cloud.

There will be a slight delay in adding 2FA-enabled repositories compared to others.  These will show in the git configuration list eventually.

In order to access a Git repository over HTTP, use the username as the username and the PAT for the password.

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

Viewing Git Commits in Jira Cloud

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

  2. Open the Jira issue on your Jira instance.

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

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

Working with Branches and Merge Requests with GitLab

This process requires a GitLab git repository and a PAT with api scope.

For GitLab Group, 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.  Auto-connected 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.

Main branch for repositories within an integration can only be changed on the git server.

Creating Branches

On your Jira Cloud instance, open a Jira issue. On the Jira developer panel under Git Integration, click Create branch. The following dialog is displayed.

Pointers:

  1. Select a Repository from the list.

    1. The selected repository will display the git service logo to identify which git host it is located from.

    2. 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.

    3. Use the search box to look for the specific repository that will be used.

    4. Optional – designate the repository to be the default selected repository for current Jira project.  To configure default repositories for more than one Jira project - use the User settings page.

  2. Choose a Base branch.

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

For more detailed information on this feature, see 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.

Creating Merge Requests

The pull request feature works the same as merge request. On your Jira Cloud, open the Jira issue where your previously created a branch. On the developer panel under Git Integration, click Create merge request. The following dialog is displayed.

Pointers:

  1. Select a Repository from the list.

    1. The selected repository will display the git service logo to identify which git host it is located from.

    2. 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.

    3. Use the search box to look for the specific repository that will be used.

    4. Optional – designate the repository to be the default selected repository for current Jira project.  To configure default repositories for more than one Jira project - use the User settings page.

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

  3. Set master as the Target branch.

  4. Enter a descriptive Title or leave it as is (recommended).

Pull/merge requests are still indexed based on branch name even if the PR/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 master).

For more detailed information on this feature, see Create Branch.

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

 

1 Logo owned by GitLab Inc used under license