- GitLab data synced to Jira
- Install the GitLab for Jira Cloud app
- Configure the GitLab for Jira Cloud app
- Update the GitLab for Jira Cloud app
- Security considerations
- Troubleshooting
GitLab for Jira Cloud app
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.
GitLab data synced to Jira
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:
- Existing project data (before you linked the group):
- The last 400 merge requests
- The last 400 branches and the last commit to each of those branches (GitLab 15.11 and later)
- New project data (after you linked the group):
- Merge requests
- Merge request author
- Branches
- Commits
- Commit author
- Pipelines
- Deployments
- Feature flags
- Merge requests
Install the GitLab for Jira Cloud app
Prerequisites:
- Your network must allow inbound and outbound connections between GitLab and Jira.
- You must meet certain Jira user requirements.
To install the GitLab for Jira Cloud app:
- In Jira, on the top bar, select Apps > Explore more apps and search for
GitLab for Jira Cloud
. - Select GitLab for Jira Cloud, then select Get it now.
Alternatively, get the app directly from the Atlassian Marketplace.
You can now configure the GitLab for Jira Cloud app.
For an overview, see Configure the GitLab for Jira Cloud app from the Atlassian Marketplace.
Configure the GitLab for Jira Cloud app
- Add namespace renamed to Link groups in GitLab 16.1.
Prerequisites:
- You must have at least the Maintainer role for the GitLab group.
- You must meet certain Jira user requirements.
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:
- In Jira, on the top bar, select Apps > Manage your apps.
- Expand GitLab for Jira. Depending on how you installed the app, the name of the app is:
- GitLab for Jira (gitlab.com) if you installed the app from the Atlassian Marketplace.
-
GitLab for Jira (
<gitlab.example.com>
) if you installed the app manually.
- Select Get started.
- Optional. To link a self-managed GitLab instance with Jira, select Change GitLab version.
- Select all checkboxes, then select Next.
- Enter your GitLab instance URL, then select Save.
- Select Sign in to GitLab, then enter your credentials.
- 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, data is synced to Jira for all projects in that group. The initial data sync happens in batches of 20 projects per minute. For groups with many projects, the data sync for some projects is delayed.
Update the GitLab for Jira Cloud app
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.
Security considerations
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.
GitLab access to Jira
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 access to GitLab
Jira does not gain any access to GitLab.
Data sent from GitLab to Jira
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.
Data sent from Jira to GitLab
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 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 self-managed instance. For more information, see GitLab.com handling of app lifecycle events.
Privacy and security details in the Atlassian Marketplace
For more information, see the privacy and security details of the Atlassian Marketplace listing.
Troubleshooting
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.
Error when connecting the app
When 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.