Jira issue integration

The Jira issue integration connects one or more GitLab projects to a Jira instance. You can host the Jira instance yourself or in Jira Cloud. The supported Jira versions are 6.x, 7.x, 8.x, and 9.x.

Configure the integration

Authentication with Jira personal access tokens introduced in GitLab 16.0.

Prerequisites:

  • Your GitLab installation must not use a relative URL.
  • For Jira Cloud, you must have a Jira Cloud API token and the email address you used to create the token.
  • For Jira Data Center or Jira Server, you must have one of the following:

You can enable the Jira issue integration by configuring your project settings in GitLab. You can configure these settings at the group level or at the instance level for self-managed GitLab.

To configure your project settings in GitLab:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Settings > Integrations.
  3. Select Jira.
  4. Under Enable integration, select the Active checkbox.
  5. Provide connection details:
    • Web URL: Base URL for the Jira instance web interface you’re linking to this GitLab project (for example, https://jira.example.com).
    • Jira API URL: Base URL for the Jira instance API (for example, https://jira-api.example.com). If this URL is not set, the Web URL value is used by default. For Jira Cloud, leave Jira API URL blank.
    • Authentication method:
      • Basic:
        • Email or username:
          • For Jira Cloud, enter an email.
          • For Jira Data Center or Jira Server, enter a username.
        • API token or password:
          • For Jira Cloud, enter an API token.
          • For Jira Data Center or Jira Server, enter a password.
      • Jira personal access token (only available for Jira Data Center and Jira Server): Enter a personal access token.
  6. Provide trigger settings:
    • Select Commit, Merge request, or both as triggers. When you mention a Jira issue ID in GitLab, GitLab links to that issue.
    • To add a comment to the Jira issue that links back to GitLab, select the Enable comments checkbox and the information that the comment displays.
    • To transition Jira issues automatically in GitLab, select the Enable Jira transitions checkbox.
  7. In the Jira issue matching section:
  8. In the Issues section:
    • To view Jira issues in a GitLab project, select the Enable Jira issues checkbox and enter a Jira project key. You can only view issues from a single Jira project in a GitLab project.
    caution
    When you enable this setting, all users with access to that GitLab project can view all issues from the Jira project you’ve specified.
  9. Optional. Select Test settings.
  10. Select Save changes.

Your GitLab project can now interact with all Jira projects in your instance, and the project displays a Jira link that opens the Jira project.

Create a Jira Cloud API token

To configure the Jira issue integration for Jira Cloud, you must have a Jira Cloud API token. To create a Jira Cloud API token:

  1. Sign in to Atlassian from an account with write access to Jira projects.

    The link opens the API tokens page. Alternatively, from your Atlassian profile, select Account Settings > Security > Create and manage API tokens.

  2. Select Create API token.
  3. On the dialog, enter a label for your token and select Create.

To copy the API token, select Copy.

Migrate from Jira Server to Jira Cloud in GitLab

To migrate from Jira Server to Jira Cloud in GitLab and maintain your Jira integration:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Settings > Integrations.
  3. Select Jira.
  4. In Web URL, enter the new Jira site URL (for example, https://myjirasite.atlassian.net).
  5. In Email or username, enter the email registered on your Jira profile.
  6. Create a Jira Cloud API token, and copy the token value.
  7. In API token or password, paste the API token value.
  8. Optional. Select Test settings.
  9. Select Save changes.

To update existing Jira issue references in GitLab to use the new Jira site URL, you must invalidate the Markdown cache.