« Table of Contents

gitlab logo GitLab.com Integration1 Jira Cloud

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 new tab/window icon.

Connecting a GitLab.com Account via 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 add-on.

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.

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

Creating a Personal Access Token

  1. Login to your GitLab account then go to your Profile Settings.
  2. Select Access Tokens on the sidebar.  The following screen is displayed:
  3. Give the token a descriptive name. (For example, "Git Integration for Jira")
  4. Leave the Expires at field blank.
  5. Select the "api" scope.
  6. Click Create personal access token.
  7. Copy the token – (Write it down or be sure to save it. This is the ONLY time you'll see the token).

Connect GitLab Repositories via Auto-Connect

  1. Go to Manage Git Repositories (Dashboard > Git menu) in Jira Cloud.
  2. Click GitLab in the Auto-connect integration panel.
  3. GitLab.com is selected by default.  Paste the personal access token in the provided field.
  4. Follow instructions in the wizard to import GitLab repositories.

There will be a slight delay in adding this repository compared to others.  It will show in the git configuration list eventually.

helpful tip
To pass the private access token (for example: XpigzF1JxMnAZ7mn9qgN) to an API call with GitLab.com:
curl --header "Private-Token: XpigzF1JxMnAZ7mn9qgN" https://gitlab.com/api/v4/projects?membership=true
note
In order to access a Git repository over HTTP, use the username as the username and the PAT for the password.

Single Repository Connections

This process requires an existing GitLab git repository.  For starters, the GitLab repository URL can be acquired 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 add-on: Manage Git Repositories > Connect to Git Repository.

fyi
The Git Integration for Jira add-on supports v3 and v4 of the GitLab API (in both Jira Cloud and Jira Server).

Working with Branches and Pull Requests with GitLab Jira Server

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

For GitHub Organization, the user must have the Write permissions and the api PAT scope.

  1. On your Jira Server, open a Jira issue.  On the Jira developer panel under Git Source Code, click Create Branch.
  2. The Create Branch dialog is displayed.
    • Select a Repository from the list.
    • 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.
    • Choose a Base branch.
    • Enter a Branch name or leave it as is (recommended).
  3. 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 pull request feature works the same as merge 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 Source Code, click Create merge request.
  3. The Create Merge Request dialog is displayed.
    • Select Repository from the list.
    • 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.
    • 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).
  4. 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.

 

« Table of Contents