doc/integration/jira/connect-app.md
{{< details >}}
{{< /details >}}
[!note] This page contains user documentation for the GitLab for Jira Cloud app. For administrator documentation, see GitLab for Jira Cloud app administration.
With the GitLab for Jira Cloud app, you can connect GitLab and Jira Cloud to sync development information in real time. You can view this information in the Jira development panel.
You can use the GitLab for Jira Cloud app to link top-level groups or subgroups. It's not possible to directly link projects or personal namespaces.
To set up the GitLab for Jira Cloud app on GitLab.com, install the GitLab for Jira Cloud app.
After you set up the app, you can use the project toolchain developed and maintained by Atlassian to link GitLab repositories to Jira projects. The project toolchain does not affect how development information is synced between GitLab and Jira Cloud.
For Jira Data Center or Jira Server, use the Jira DVCS connector developed and maintained by Atlassian.
After you link a group, the following GitLab data is synced to Jira for all projects in that group when you mention a Jira issue ID:
{{< details >}}
{{< /details >}}
Prerequisites:
To install the GitLab for Jira Cloud app:
GitLab for Jira Cloud.Alternatively, get the app directly from the Atlassian Marketplace.
You can now configure the GitLab for Jira Cloud app.
<i class="fa-youtube-play" aria-hidden="true"></i> For an overview, see installing the GitLab for Jira Cloud app from the Atlassian Marketplace for GitLab.com.
<!-- Video published on 2024-10-30 -->The video above shows the older Universal Plugin Manager interface which might be unavailable on newer Jira Cloud instances. The following instructions cover both old and new app management interfaces.
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
Prerequisites:
You can sync data from GitLab to Jira by linking the GitLab for Jira Cloud app to one or more GitLab groups. To configure the GitLab for Jira Cloud app:
<!-- markdownlint-disable MD044 -->In Jira, select the horizontal ellipsis ({{< icon name="ellipsis_h" >}}) beside Apps and select Manage your apps.
Navigate to the app using one of these methods:
For instances with centralized app management:
<gitlab.example.com>) if you installed the app manually.For instances with legacy app management:
<gitlab.example.com>) if you installed the app manually.Optional. To link GitLab Self-Managed with Jira, select Change GitLab version.
Select Sign in to GitLab.
[!note] Enterprise users with disabled password authentication for their group must first sign in to GitLab with their group's single sign-on URL.
GitLab requires you to sign in to link groups, but does not tie the configuration to a specific user. The GitLab instance receives a token from Jira that is used to update information in Jira. For more information, see GitLab access to Jira.
Select Authorize. A list of groups is now visible.
Select Link groups.
To link to a group, select Link.
After you link to a GitLab group:
{{< history >}}
enable_jira_connect_configuration. Disabled by default.enable_jira_connect_configuration removed.{{< /history >}}
[!note] This feature was added as a community contribution and is developed and maintained by the GitLab community only.
Prerequisites:
You can connect GitLab to your IT service project to track your deployments.
Configuration happens in GitLab, in the GitLab for Jira Cloud app integration. The integration is enabled for a group, its subgroups, and projects in GitLab after a GitLab group has been linked.
Enabling and disabling the GitLab for Jira Cloud app integration happens entirely automatically through group linking, and not through the GitLab integrations form or API.
In Jira Service Management:
In GitLab:
You can map up to 100 services.
For more information about deployment tracking in Jira, see set up deployment tracking.
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
[!note] This feature was added as a community contribution and is developed and maintained by the GitLab community only.
You can set up deployment gating to bring change requests from GitLab to Jira Service Management for approval. With deployment gating, any GitLab deployments to your selected environments are automatically sent to Jira Service Management and are only deployed if they're approved.
To create a service account token in GitLab, you must first create a personal access token. This token authenticates the service account token used to manage GitLab deployments in Jira Service Management.
To create the service account token:
To enable deployment gating:
In GitLab:
production, staging, testing, development).
Use lowercase letters only.In Jira Service Management:
To add the service account to your protected environments in GitLab:
Create a service account user:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=<name_of_your_choice>&username=<username_of_your_choice>" "<https://gitlab.com/api/v4/groups/<group_id>/service_accounts"
Add the service account to a group or project by using your personal access token:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--data "user_id=<service_account_id>&access_level=30" "https://gitlab.com/api/v4/groups/<group_id>/members"
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--data "user_id=<service_account_id>&access_level=30" "https://gitlab.com/api/v4/projects/<project_id>/members"
Generate a service account token by using your personal access token:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>"
"https://gitlab.com/api/v4/groups/<group_id>/service_accounts/<service_account_id>/personal_access_tokens" --data "scopes[]=api,read_user,read_repository" --data "name=service_accounts_token"
Most updates to the app are automatic. For more information, see the Atlassian documentation.
If the app requires additional permissions, you must manually approve the update in Jira.
{{< history >}}
{{< /history >}}
The GitLab for Jira Cloud app has been migrated from Atlassian Connect to Atlassian Forge. This change follows the end-of-support announcement for Connect apps by Atlassian.
All existing features continue to work, including:
If you installed the GitLab for Jira Cloud app from the Atlassian Marketplace:
If you installed the GitLab for Jira Cloud app manually, the migration to Forge also affects your installation. This installation method is based on Atlassian Connect.
For more information about the transition from Connect to Forge, see the Atlassian guide on how to adopt Forge.
The GitLab for Jira Cloud app connects GitLab and Jira. Data must be shared between the two applications, and access must be granted in both directions.
When you configure the GitLab for Jira Cloud app, GitLab receives a shared secret token from Jira.
The token grants GitLab READ, WRITE, and DELETE app scopes for the Jira project.
These scopes are required to update information in the Jira project's development panel.
The token does not grant GitLab access to any other Atlassian product besides the Jira project the app was installed in.
The token is encrypted with AES256-GCM and stored on GitLab.
When the GitLab for Jira Cloud app is uninstalled from your Jira project, GitLab deletes the token.
Jira does not gain any access to GitLab.
For all the data sent to Jira, see GitLab data synced to Jira.
For more information about the specific data properties sent to Jira, see the serializer classes involved in data synchronization.
GitLab receives a lifecycle event from Jira when the GitLab for Jira Cloud app is installed or uninstalled. The event includes a token to verify subsequent lifecycle events and to authenticate when sending data to Jira. Lifecycle event requests from Jira are verified.
For GitLab Self-Managed instances that use the GitLab for Jira Cloud app from the Atlassian Marketplace, GitLab.com handles lifecycle events and forwards them to the GitLab Self-Managed instance. For more information, see GitLab.com handling of app lifecycle events.
Data sent to Jira is stored by Jira and displayed in the Jira development panel.
When the GitLab for Jira Cloud app is uninstalled, Jira permanently deletes this data. This process happens asynchronously and might take up to several hours.
For more information, see the privacy and security details of the Atlassian Marketplace listing.
When working with the GitLab for Jira Cloud app, you might encounter the following issues.
For administrator documentation, see GitLab for Jira Cloud app administration.
Failed to link groupWhen you connect the GitLab for Jira Cloud app, you might get this error:
Failed to link group. Please try again.
A 403 Forbidden is returned if the user information cannot be fetched from Jira because of insufficient permissions.
To resolve this issue, ensure you meet certain Jira user requirements.
If the Jira user has administrator privileges but is not explicitly a member of
the site-admins or org-admins group, see
Error: The Jira user is not a site or organization administrator.
Jira Code might not work after you link the GitLab for Jira Cloud app to a GitLab group. To resolve this issue, you must configure both Bitbucket and Jira.
In Bitbucket:
In Jira:
Your repositories should now appear in Jira Code.
For more information, see issue JRACLOUD-95847.