« Table of Contents

gitlab server logo GitLab Server EE/CE Integration1 Jira Server

Introduced in v2.9.4 of the Git add-on, 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 add-on offers pre-v10 GitLab Server service users as a Legacy connection option.

helpful tip
BigBrassBand recommends a dedicated user for this integration which has access permissions to the GitLab git repositories.

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 to a GitLab Server Jira Server

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.

  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 Auto-connect integration panel, click GitLab.
  4. On the Connect to GitLab screen, select the External service from the dropdown list.
  5. Choose:
    • GitLab Server (CE/EE) Legacy  –  if your GitLab Server version is 10.1 and older.
    • Enter the Host URL of the GitLab server.  Enter the username and password credentials for server authentication.  If 2FA is enabled in your GitLab Server, enter the personal access token as the password.
    • GitLab Server (CE/EE)  –  if your GitLab Server version is 10.2 and newer.
    • 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 maximum allowed length is 2000 characters or less.

      The integration will use the relative REST API path to retrieve the list of tracked repositories.

      The Custom API Path is called everytime the list of repositories is loaded, on a regular scheduled reindex and a manual reindex.

    • Examples:

      /api/v4/projects?membership=true

      Gets a list of projects. This is the same as when no API path is specified.

      /api/v4/users/<user_id>/projects

      Gets a list of projects for the specified user, <user_id>. johnsmith

      /api/v4/projects?starred=true

      Returns GitLab projects that have been starred by the connecting GitLab user.

      /api/v4/projects?owned=true

      The current user will be limited to the projects it's explicitly owned.

      For more information on GitLab custom API paths, see GitLab API opens in new tab/window.

      note
      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.
    • JMESPath filter  –  JMESPath is a query language for JSON used to filter API results and to limit which repositories are integrated.  For help with writing expressions, please contact support mail icon.
    • Read about JMESPath expressions on their website opens in new tab/window.

      The maximum allowed length is 2000 characters or less.

      Example: [?contains(name, 'git') || contains(name, 'Slap') || contains(name, 'est')].

      This is a filter based on text in the repository name. It will list all the repositories that contain the specified names. Do note that the declared string format is case-sensitive.

    While Custom API Path and JMESPath filter are mutually exclusive, you can use one, the other, both or neither.
  6. Click Connect. The Git add-on will import detected GitLab Enterprise repositories.
  7. note
    Currently, the Git add-on 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.
  8. After the import process, the Settings dialog is displayed:
  9. Click Finish.

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 Git Repositories page under cog Actions  > Show tracked repositories to modify tracked repositories settings.

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

fyi
The Git Integration for Jira add-on supports v3 and v4 of the GitLab API (in both Jira Cloud and Jira Server).
helpful tip
For newer GitLab authentication - in order to access a Git repository over HTTP, use the username as the username and the PAT for the password.
Admin/Power Users:
To pass the private access token (for example: XpigzF1JxMnAZ7mn9qgN) to an API call with GitLab:
curl --header "Private-Token: XpigzF1JxMnAZ7mn9qgN" https://gitlab.com/api/v4/projects?membership=true

Single Repository Connections

This process requires an existing GitLab CE/EE 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 app: Manage Git Repositories > Connect to Git Repository.

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

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

Working with Branches and Merge Requests with GitLab CE/EE Jira Cloud

For GitLab CE/EE (Legacy or newer), 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.
    • 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:
    • Click the link label to setup the PAT.  This will show the Repository Browser listing connected git repositories.
    • 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.
  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 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 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).

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

    Configure a PAT for the selected repository. Otherwise, the merge request creation will fail.

  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 CE/EE web portal.

 

« Table of Contents