Jira DVCS connector

Use the Jira DVCS (distributed version control system) connector if you self-host either your Jira instance or your GitLab instance, and you want to sync information between them. If you use Jira Cloud and GitLab.com, you should use the GitLab for Jira app unless you specifically need the DVCS connector.

When you configure the Jira DVCS connector, make sure your GitLab and Jira instances are accessible.

  • Self-managed GitLab: Your GitLab instance must be accessible by Jira.
  • Jira Cloud: Your instance must be accessible through the internet.
  • Jira Server: Your network must allow access to your instance.

Smart commits

When connecting GitLab with Jira with DVCS, you can process your Jira issues using special commands, called Smart Commits, in your commit messages. With Smart Commits, you can:

  • Comment on issues.
  • Record time-tracking information against issues.
  • Transition issues to any status defined in the Jira project’s workflow.

Commands must be in the first line of the commit message. The Jira Software documentation contains more information about how Smart Commits work, and what commands are available for your use.

For Smart Commits to work, the committing user on GitLab must have a corresponding user on Jira with the same email address or username.

Smart Commit syntax

Smart Commits should follow the pattern of: 

<ISSUE_KEY> <ignored text> #<command> <optional command parameters>

Some examples:

  • Adding a comment to a Jira issue: KEY-123 fixes a bug #comment Bug is fixed.
  • Recording time tracking: KEY-123 #time 2w 4d 10h 52m Tracking work time.
  • Closing an issue: KEY-123 #close Closing issue

A Smart Commit message must not span more than one line (no carriage returns) but you can still perform multiple actions in a single commit:

  • Time tracking, commenting, and transitioning to Closed: KEY-123 #time 2d 5h #comment Task completed ahead of schedule #close.
  • Commenting, transitioning to In-progress, and time tracking: KEY-123 #comment started working on the issue #in-progress #time 12d 5h.

Configure a GitLab application for DVCS

We recommend you create and use a jira user in GitLab, and use the account only for integration work. A separate account ensures regular account maintenance does not affect your integration.

  1. In GitLab, create a user for Jira to use to connect to GitLab. For Jira to access all projects, a user with Administrator permissions must create the user.
  2. In the top right corner, click the account’s avatar, and select Edit profile.
  3. In the left sidebar, select Applications.
  4. In the Name field, enter a descriptive name for the integration, such as Jira.
  5. In the Redirect URI field, enter the URI appropriate for your version of GitLab, replacing <gitlab.example.com> with your GitLab instance domain:
    • For GitLab versions 13.0 and later and Jira versions 8.14 and later, use the generated Redirect URL from Linking GitLab accounts with Jira.
    • For GitLab versions 11.3 and later, use https://<gitlab.example.com>/login/oauth/callback. If you use GitLab.com, the URL is https://gitlab.com/login/oauth/callback.
    • For GitLab versions 11.2 and earlier, use https://<gitlab.example.com>/-/jira/login/oauth/callback.
  6. For Scopes, select api and clear any other checkboxes.
  7. Select Submit.
  8. GitLab displays the generated Application ID and Secret values. Copy these values, as you need them to configure Jira.

Configure Jira for DVCS

If you use Jira Cloud and GitLab.com, use the GitLab for Jira app unless you specifically need the DVCS Connector.

Configure this connection when you want to import all GitLab commits and branches, for the groups you specify, into Jira. This import takes a few minutes and, after it completes, refreshes every 60 minutes:

  1. Ensure you have completed the GitLab configuration.
  2. Go to your DVCS accounts:
    • For Jira Server, go to Settings (gear) > Applications > DVCS accounts.
    • For Jira Cloud, go to Settings (gear) > Products > DVCS accounts.
  3. To create a new integration, select the appropriate value for Host:
    • For Jira versions 8.14 and later: Select GitLab or GitLab Self-Managed.
    • For Jira versions 8.13 and earlier: Select GitHub Enterprise.
  4. For Team or User Account, enter either:
    • For Jira versions 8.14 and later:
      • The relative path of a top-level GitLab group that you have access to.
    • For Jira versions 8.13 and earlier:
      • The relative path of a top-level GitLab group that you have access to.
      • The relative path of your personal namespace.
  5. In the Host URL field, enter the URI appropriate for your version of GitLab, replacing <gitlab.example.com> with your GitLab instance domain:
    • For GitLab versions 11.3 and later, use https://<gitlab.example.com>.
    • For GitLab versions 11.2 and earlier, use https://<gitlab.example.com>/-/jira.
  6. For Client ID, use the Application ID value from the previous section.
  7. For Client Secret, use the Secret value from the previous section.
  8. Ensure that the rest of the checkboxes are checked.
  9. Select Add and then Continue to create the DVCS account.
  10. Jira redirects to GitLab where you have to confirm the authorization, and then GitLab redirects back to Jira where you should see the synced projects show up inside the new account.

To connect additional GitLab projects from other GitLab top-level groups, or personal namespaces, repeat the previous steps with additional Jira DVCS accounts.

After you configure the integration, read more about how to test and use it.

Refresh data imported to Jira

Jira imports the commits and branches every 60 minutes for your projects. You can refresh the data manually from the Jira interface:

  1. Sign in to your Jira instance as the user you configured the integration with.
  2. Go to Settings (gear) > Applications.
  3. Select DVCS accounts.
  4. In the table, for the repository you want to refresh, in the Last Activity column, select the icon: Refresh GitLab information in Jira

Troubleshooting your DVCS connection

Refer to the items in this section if you’re having problems with your DVCS connector.

Jira cannot access GitLab server

If you complete the Add New Account form, authorize access, and you receive this error, Jira and GitLab cannot connect. No other error messages appear in any logs: 

Error obtaining access token. Cannot access https://gitlab.example.com from Jira.

SSL and TLS problems

Problems with SSL and TLS can cause this error message: 

Error obtaining access token. Cannot access https://gitlab.example.com from Jira.
  • The GitLab Jira integration requires GitLab to connect to Jira. Any TLS issues that arise from a private certificate authority or self-signed certificate are resolved on the GitLab server, as GitLab is the TLS client.
  • The Jira Development panel integration requires Jira to connect to GitLab, which causes Jira to be the TLS client. If your GitLab server’s certificate is not issued by a public certificate authority, the Java Truststore on Jira’s server must have the appropriate certificate (such as your organization’s root certificate) added to it .

Refer to Atlassian’s documentation and Atlassian Support for assistance setting up Jira correctly:

  • Add a certificate to the trust store.
    • The simplest approach is keytool.
    • Add additional roots to Java’s default Truststore (cacerts) to allow Jira to also trust public certificate authorities.
    • If the integration stops working after upgrading Jira’s Java runtime, the cacerts Truststore may have been replaced during the upgrade.
  • Troubleshooting connectivity up to and including TLS handshaking, using the a java class called SSLPoke.
  • Download the class from Atlassian’s knowledge base to a directory on Jira’s server, such as /tmp.
  • Use the same Java runtime as Jira.
  • Pass all networking-related parameters that Jira is called with, such as proxy settings or an alternative root Truststore (-Djavax.net.ssl.trustStore): 
${JAVA_HOME}/bin/java -Djavax.net.ssl.trustStore=/var/atlassian/application-data/jira/cacerts -classpath /tmp SSLPoke gitlab.example.com 443

The message Successfully connected indicates a successful TLS handshake.

If there are problems, the Java TLS library generates errors that you can look up for more detail.

Scope error when connecting Jira via DVCS 

The requested scope is invalid, unknown, or malformed.

Potential resolutions:

  1. Verify that the URL shown in the browser after being redirected from Jira in the Jira DVCS connector setup includes scope=api in the query string.
  2. If scope=api is missing from the URL, edit the GitLab account configuration. Review the Scopes field and ensure the api check box is selected.

Jira error adding account and no repositories listed

After you complete the Add New Account form in Jira and authorize access, you might encounter these issues:

  • An Error! Failed adding the account: [Error retrieving list of repositories] error.
  • An Account is already integrated with JIRA error when you click Try Again.
  • An account is visible in the DVCS accounts view, but no repositories are listed.

To resolve this issue:

  • If you’re using GitLab Free, be sure you’re using GitLab 13.4 or later.
  • If you’re using GitLab versions 11.10-12.7, upgrade to GitLab 12.8.10 or later to resolve an identified issue.

Contact GitLab Support if none of these reasons apply.

Fix synchronization issues

If Jira displays incorrect information, such as deleted branches, you may need to resynchronize the information. To do so:

  1. In Jira, go to Jira Administration > Applications > DVCS accounts.
  2. At the account (group or subgroup) level, Jira displays an option to Refresh repositories in the (ellipsis) menu.
  3. For each project, there’s a sync button displayed next to the last activity date.
    • To perform a soft resync, click the button.
    • To complete a full sync, shift-click the button.

For more information, read Atlassian’s documentation.