Integration Guide

gitlab logo GitLab.com Integration1 Jira Server

Acquiring GitLab.com URL for Single Repository Connection

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.

GitLab repository home

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

Connecting to a GitLab.com Account

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. GitLab MFA generate access token
  4. Give the token a descriptive name. (For example, "Git Integration for Jira")
  5. Leave the Expires at field blank.
  6. Select the "api" scope.
  7. Click Create personal access token.
  8. Copy the token – (Write it down or be sure to save it. This is the ONLY time you'll see the token).
take note
In your GitLab.com repository account setting, the api scopes of the PAT has the ability to create branches and pull request to specified GitLab.com repositories via developer panel of a Jira issue.

Connecting GitLab.com Git Repositories to Jira Server

  1. Go to Manage Git Repositories (Dashboard > Git menu) in Jira Server.
  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. Connect to GitLab.com Authentication screen
  5. On the following screen, Git Integration for Jira add-on will read all available repositories from your GitLab.com account.  Click Import repositories.
  6. Repositories of the logged-in GitLab.com user can be automatically connected to Jira Server.  Repositories that are added or removed from GitLab.com will be likewise connected or disconnected from Jira Server.
  7. After the import process, the Settings dialog is displayed:
  8. jira server connect vsts settings dialog
    • On the Integration Settings, setting the Require User PAT option to ON, will require users to provide PAT specific for branch and merge requests creation/deletion (via the developer panel open in new tab on the Jira issue page). For more information on this feature, see Integration Settings: Require User PAT icons.
    • Set Smart Commits open in new tab and Repository Browser open in new tab to enable/disable these features.
    • Set Project Permissions according to your organization's project association rules.
  9. Click Finish.

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

helpful tip
Admin/Power Users:
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.

 

Working with Branches and Pull Requests with GitLab Jira Server

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.

  1. On your Jira Server, open a Jira issue.  On the Jira developer panel under Git Source Code, click Create Branch.
  2. The following dialog is displayed:
  3. Jira server issue page create branch dialog
    • 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).
    If the Require User PAT option icons  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: jira server issue create branch dlg PAT required
    • Click the link label to setup the PAT.  This will show the Repository Browser listing connected git repositories.
    • jira server repository browser enter user PAT
    • Click the  icons  icon to setup a PAT for the selected repository.  Paste a valid PAT of the current user to proceed.  Invalid PATs will fail the branch creation process.
    • Click  icons  to use this PAT and save it to the current user profile. Click  icons   to cancel setting up PAT for this repository.
    • After the above steps have been taken, the users will be able to proceed with branch creation.
  4. 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 following dialog is displayed:
  4. Jira issue page create pull request dialog
    • 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).

    If the Require User PAT option icons is enabled and a user PAT isn't configured yet for the selected repository via Repository Browser, the dialog below is displayed instead:

    jira server issue page create pat dialog requiring to setup pat

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

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