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.

To set up the GitLab for Jira Cloud app on your GitLab Self-Managed instance, do one of the following:

• Install the GitLab for Jira Cloud app from the Atlassian Marketplace.
• Install the GitLab for Jira Cloud app manually.

For an overview, see:

• Installing the GitLab for Jira Cloud app from the Atlassian Marketplace for a GitLab Self-Managed instance
• Installing the GitLab for Jira Cloud app manually for a GitLab Self-Managed instance (Forge app)

The videos above show 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.

If you install the GitLab for Jira Cloud app from the Atlassian Marketplace, 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.

Set up OAuth authentication

Whether you want to install the GitLab for Jira Cloud app from the Atlassian Marketplace or manually, you must create an OAuth application.

Prerequisites:

• Administrator access.

To create an OAuth application on your GitLab Self-Managed instance:

1. In the upper-right corner, select Admin.

2. In the left sidebar, select Applications.

3. Select New application.

4. In Redirect URI:

   • If you’re installing the app from the Atlassian Marketplace listing, enter https://gitlab.com/-/jira_connect/oauth_callbacks.
   • If you’re installing the app manually, enter <instance_url>/-/jira_connect/oauth_callbacks and replace <instance_url> with the URL of your instance.

5. Clear the Trusted and Confidential checkboxes.

   You must clear these checkboxes to avoid sign in errors.

6. In Scopes, select the api checkbox only.

7. Select Save application.

8. Copy the Application ID value.

9. In the left sidebar, select Settings > General.

10. Expand GitLab for Jira App.

11. Paste the Application ID value into Jira Connect Application ID.

12. Select Save changes.

Jira user requirements

In your Atlassian organization, you must ensure that the Jira user that is used to set up the GitLab for Jira Cloud app is a member of either:

• The Organization Administrators (org-admins) group. Newer Atlassian organizations are using centralized user management, which contains the org-admins group. Existing Atlassian organizations are being migrated to centralized user management. If available, you should use the org-admins group to indicate which Jira users can manage the GitLab for Jira Cloud app. Alternatively you can use the site-admins group.
• The Site Administrators (site-admins) group. The site-admins group was used under original user management.

If necessary:

1. Create your preferred group.
2. Edit the group to add your Jira user as a member of it.
3. If you customized your global permissions in Jira, you might also need to grant the Browse users and groups permission to the Jira user.

Install the GitLab for Jira Cloud app from the Atlassian Marketplace

You can use the official GitLab for Jira Cloud app from the Atlassian Marketplace with your GitLab Self-Managed instance.

With this method:

• GitLab.com handles the install and uninstall lifecycle events sent from Jira Cloud and forwards them to your GitLab instance. All data from your GitLab Self-Managed instance is still sent directly to Jira Cloud.
• GitLab.com handles branch creation links by redirecting them to your instance.
• With any version of GitLab prior to 17.2 it is not possible to create branches from Jira Cloud on GitLab Self-Managed instances. For more information, see issue 391432.

Alternatively, you might want to install the GitLab for Jira Cloud app manually if:

• Your instance does not meet the prerequisites.
• You do not want to use the official Atlassian Marketplace listing.
• You do not want GitLab.com to handle the app lifecycle events or to know that your instance has installed the app.
• You do not want GitLab.com to redirect branch creation links to your instance.

Prerequisites

• The instance must be publicly available.
• The instance must be on GitLab version 15.7 or later.
• You must set up OAuth authentication.
• Your GitLab instance must use HTTPS and your GitLab certificate must be publicly trusted or contain the full chain certificate.
• Your network configuration must allow:
  • Outbound connections from your GitLab Self-Managed instance to Jira Cloud (Atlassian IP addresses)
  • Inbound and outbound connections between your GitLab Self-Managed instance and GitLab.com (GitLab.com IP addresses)
  • For instances behind a firewall:
    1. Set up an internet-facing reverse proxy in front of your GitLab Self-Managed instance.
    2. Configure the reverse proxy to allow inbound connections from GitLab.com (GitLab.com IP addresses)
    3. Ensure your GitLab Self-Managed instance can still make the outbound connections described previously.
• The Jira user that installs and configures the app must meet certain requirements.

Set up your instance for Atlassian Marketplace installation

Prerequisites

To set up your GitLab Self-Managed instance for Atlassian Marketplace installation:

1. In the upper-right corner, select Admin.
2. In the left sidebar, select Settings > General.
3. Expand GitLab for Jira App.
4. In Jira Connect Proxy URL, enter https://gitlab.com to install the app from the Atlassian Marketplace.
5. Select Save changes.

Link your instance

Prerequisites

To link your GitLab Self-Managed instance to the GitLab for Jira Cloud app:

1. Install the GitLab for Jira Cloud app.
2. Configure the GitLab for Jira Cloud app.
3. Optional. Check if Jira Cloud is now linked.

Check if Jira Cloud is linked

You can use the Rails console to check if Jira Cloud is linked to:

• A specific group:

  ruby

  JiraConnectSubscription.where(namespace: Namespace.by_path('group/subgroup'))

• A specific project:

  ruby

  Project.find_by_full_path('path/to/project').jira_subscription_exists?

• Any group:

  ruby

  installation = JiraConnectInstallation.find_by_base_url("https://customer_name.atlassian.net")
  installation.subscriptions

Install the GitLab for Jira Cloud app manually

Install the GitLab for Jira Cloud app manually if you cannot use the official Atlassian Marketplace listing. For example, if:

• Your instance does not meet the Marketplace prerequisites.
• You do not want GitLab.com to handle app lifecycle events or to know that your instance has installed the app.
• You do not want GitLab.com to redirect branch creation links to your instance.

The manual install method is now based on Atlassian Forge. You publish a private copy of the GitLab for Jira Cloud Forge app under your own Atlassian developer account, pointed at your GitLab Self-Managed or GitLab Dedicated instance.

Prerequisites

• The instance must be publicly available over HTTPS, with a publicly trusted certificate.
• You must set up OAuth authentication.
• Your network configuration must allow:
  • Inbound HTTPS connections from Jira Cloud to <instance_url>/-/jira_connect (Atlassian IP addresses).
  • Outbound HTTPS connections from your GitLab instance to *.atlassian.net to push development data to Jira.
  • For instances behind a firewall:
    1. Set up an internet-facing reverse proxy in front of your GitLab Self-Managed instance.
    2. Configure the reverse proxy to allow inbound connections from Jira Cloud.
    3. Ensure your GitLab Self-Managed instance can still make the outbound connections described previously.
• Instances in an offline environment cannot use the integration. The outbound path to *.atlassian.net is required for the development panel and other Jira-side surfaces.
• The Jira user that installs and configures the app must meet certain requirements.
• An Atlassian developer account and an Atlassian API token for the Forge CLI.
• A machine with Node.js 22 LTS, the Forge CLI, envsubst, git, and curl.

Set up your instance for manual installation

Prerequisites

To set up your GitLab Self-Managed instance for manual installation:

1. In the upper-right corner, select Admin.
2. In the left sidebar, select Settings > General.
3. Expand GitLab for Jira App.
4. Leave Jira Connect Proxy URL blank to install the app manually.
5. Select Save changes.

Publish a private Forge app

To publish a private copy of the GitLab for Jira Cloud Forge app and install it on your Jira site:

1. Clone the gitlab-jira-forge repository:

   shell

   git clone --depth 1 https://gitlab.com/gitlab-org/gitlab-jira-forge.git
   cd gitlab-jira-forge

2. Export the required environment variables. Replace the example values with your GitLab instance URL, Jira site, and Atlassian credentials:

   shell

   export GITLAB_URL=https://gitlab.example.com
   export JIRA_SITE=acme.atlassian.net
   export FORGE_EMAIL=admin@example.com
   export FORGE_API_TOKEN=<your-atlassian-api-token>

3. Run the wrapper script to register, deploy, and install the app:

   shell

   ./scripts/install-self-managed.sh

   The wrapper:

   • Verifies the required tools and variables.
   • Runs forge register on first use to create a Forge app under your Atlassian account.
   • Generates manifest.yml from the template, pinned to your GITLAB_URL.
   • Runs forge deploy -e production.
   • Runs forge install --site $JIRA_SITE --product jira.

   The script caches the registered APP_ID in .env.self-managed. Back up this file: if you lose it, you must re-register the app, which forces all installed Jira sites to re-install.

For step-by-step instructions, manual forge commands, troubleshooting, and the upgrade workflow, see the GitLab Self-Managed install guide in the gitlab-jira-forge repository.

After the app is registered, set its Forge app ID in GitLab so that inbound Forge tokens are verified:

1. Copy the APP_ID value (an ari:cloud:ecosystem::app/<uuid> Atlassian Resource Identifier, or ARI) from .env.self-managed.
2. In the upper-right corner, select Admin.
3. In the left sidebar, select Settings > General.
4. Expand GitLab for Jira App.
5. In Forge app ID, paste the ARI, then select Save changes.

After the app is installed, configure the GitLab for Jira Cloud app in Jira to link your GitLab namespaces.

Update the manually installed app

To pull upstream manifest changes into your private Forge app, re-run the wrapper with --update:

./scripts/install-self-managed.sh --update

The script fast-forwards the local clone, regenerates the manifest, and redeploys the app. For more information about minor and major version upgrades, see Upgrading in the GitLab Self-Managed install guide.

Switch installation methods

You can switch the GitLab for Jira Cloud app between a manual installation and the Atlassian Marketplace listing. A switch in either direction does not keep group links. If you have a Connect-based manual installation, you can migrate it to a private Forge app and keep your links.

Compare installation methods

You can install the GitLab for Jira Cloud app from the Atlassian Marketplace or as a private Forge app that you publish yourself. Each method has different requirements.

Group links and synced data belong to the installed app.

App keys and group links

GitLab stores group links on the installation record of each installed app. Jira gives each installed app on a site its own client key. GitLab keeps links only when the new app registers with the same Connect app key as the old app.

GitLab builds the Connect app key as gitlab-jira-connect-<host>. When Jira Connect Proxy URL is blank, <host> is the hostname of your instance. When Jira Connect Proxy URL is https://gitlab.com, <host> is gitlab.com. The Marketplace app therefore never matches a manual installation, and links do not carry over between the two methods.

Replacing the Jira Connect Application ID does not affect data sync. It affects only the sign-in step on the app configuration page.

Record your group links

Record the linked groups before a switch or migration, and compare them with the linked groups afterward. Use one of these methods:

• In Jira, open the GitLab for Jira Cloud app configuration page. The page lists the linked groups. Use this method on GitLab Dedicated.

• In a Rails console, run the following. Replace the URL with your Jira site:

  ruby

  JiraConnectInstallation.where(base_url: 'https://example.atlassian.net').map do |installation|
    [installation.id, installation.subscriptions.map { |subscription| subscription.namespace.full_path }]
  end

Switch from a manual installation to the Atlassian Marketplace listing

This switch does not keep group links. GitLab deletes the links of the manual installation when you uninstall the manual app. Jira deletes the development information that the manual app sent. This deletion is asynchronous and can take several hours. After you link the groups again, GitLab runs an initial sync. For each project, the initial sync includes the last 400 merge requests and the last 400 branches (with last commit) that mention a Jira issue key. GitLab processes projects in batches of 20 per minute. Pipelines, deployments, and feature flags sync only for events after you link the groups.

Nothing syncs between when you change Jira Connect Proxy URL and when you link the groups again. Merge requests and branches from that window sync during the initial sync, up to its limits.

Prerequisites:

• Administrator access.
• An instance that meets the Marketplace prerequisites.
• No other instance in your Atlassian organization that uses the Marketplace listing.

To switch:

1. Record your group links.
2. Add https://gitlab.com/-/jira_connect/oauth_callbacks as an additional redirect URI to your existing OAuth application. You do not need a second OAuth application. In the Redirect URI text box, put each URI on its own line. Keep the Jira Connect Application ID unchanged.
3. In the Admin area, in Settings > General, in the GitLab for Jira App section, set Jira Connect Proxy URL to https://gitlab.com and select Save changes. This step starts the switch. Sync of the manual app stops now.
4. Install the Marketplace app. Link your instance and the groups from your list. For more information, see Link your instance.
5. Wait for the initial sync, then check the development panel in Jira.
6. Uninstall the manual app.

While both apps are installed on the same Jira site, the development panel can show data from both.

Switch from the Atlassian Marketplace listing to a private Forge app

This switch does not keep group links. The effects on links and development data are the same as in Switch from a manual installation to the Atlassian Marketplace listing.

Prerequisites:

• Administrator access.
• An instance and tools that meet the manual installation prerequisites.

To switch:

1. Record your group links.
2. Add https://gitlab.example.com/-/jira_connect/oauth_callbacks as an additional redirect URI to your existing OAuth application. You do not need a second OAuth application. In the Redirect URI text box, put each URI on its own line. Keep the Jira Connect Application ID unchanged.
3. In the Admin area, in Settings > General, in the GitLab for Jira App section, clear Jira Connect Proxy URL and select Save changes. This step starts the switch. Sync of the Marketplace app stops now.
4. Publish and install the private Forge app. For more information, see Publish a private Forge app.
5. Link your groups again from your list.
6. Uninstall the Marketplace app.

Roll back a switch

To roll back a switch from a manual installation to the Marketplace listing before you uninstall the manual app, clear Jira Connect Proxy URL and uninstall the Marketplace app. The manual app resumes with its links intact.

After you uninstall the manual app, GitLab deletes its group links. You cannot reinstall a Connect-based manual app, because Atlassian disabled Connect-based private installations. A new private Forge app starts with no links.

To roll back a switch from the Marketplace listing to a private Forge app before you uninstall the Marketplace app, set Jira Connect Proxy URL back to https://gitlab.com and uninstall the private Forge app. The Marketplace app resumes with its links intact.

Test a switch on a Jira sandbox site

Each Jira sandbox site has its own app installation, so you can test the installation, sign-in, and linking steps there. Jira Connect Proxy URL is an instance-wide setting, so a test on your production GitLab instance also stops sync for your production Jira site. Test with a non-production GitLab instance, or plan for the sync pause. A test on a sandbox site cannot confirm that links carry over for your production Jira site.

Connect multiple GitLab instances

Use the GitLab for Jira app to connect multiple GitLab instances to a single Jira Cloud instance. The installation methods depend on which instances you want to connect.

Prerequisites:

• Each instance requires separate OAuth authentication.
• You must meet the prerequisites for each installation method.

For GitLab.com + GitLab Self-Managed:

• On GitLab.com: Use the Atlassian Marketplace installation.
• On GitLab Self-Managed instances: Install the app manually.

For multiple GitLab Self-Managed instances:

• On the first instance, either: Use the Atlassian Marketplace installation or install the app manually.
• On other instances: Install the app manually.

Jira Cloud displays a GitLab for Jira Cloud app for each installation.

Only one GitLab instance per organization can use the official Atlassian Marketplace listing.

Configure your GitLab instance to serve as a proxy

A GitLab instance can serve as a proxy for other GitLab instances through the GitLab for Jira Cloud app. You might want to use a proxy if you’re managing multiple GitLab instances but only want to manually install the app once.

To configure your GitLab instance to serve as a proxy:

1. In the upper-right corner, select Admin.
2. In the left sidebar, select Settings > General.
3. Expand GitLab for Jira App.
4. Select Enable public key storage.
5. Select Save changes.
6. Install the GitLab for Jira Cloud app manually.

Other GitLab instances that use the proxy must configure the following settings to point to the proxy instance:

• Jira Connect Proxy URL
• Redirect URI

Restrict Jira domains that can install the app

Configure an allowlist to restrict which Jira domains can install the GitLab for Jira Cloud app on your instance. Each entry must match the Jira site hostname exactly. For example, atlassian.net does not allow example.atlassian.net. If the allowlist is empty, all Jira domains can install the app.

The allowlist applies only to the Connect version of the app. It does not restrict the Forge version.

Prerequisites:

• Administrator access.

To restrict Jira domains that can install the app:

1. In the upper-right corner, select Admin.
2. In the left sidebar, select Settings > General.
3. Expand GitLab for Jira App.
4. In Jira Connect domain allowlist, enter one Jira domain per line.
5. Select Save changes.

Security considerations

The following security considerations are specific to administering the app. For considerations related to using the app, see security considerations.

GitLab.com handling of app lifecycle events

When you Install the GitLab for Jira Cloud app from the Atlassian Marketplace, GitLab.com receives lifecycle events from Jira. These events are limited to when the app is installed in or uninstalled from your Jira Project.

In the install event, GitLab.com receives a secret token from Jira. GitLab.com stores this token encrypted with AES256-GCM to later verify incoming lifecycle events from Jira.

GitLab.com then forwards the token to your GitLab Self-Managed instance so your instance can authenticate its requests to Jira with the same token. Your GitLab Self-Managed instance is also notified that the GitLab for Jira Cloud app has been installed or uninstalled.

When data is sent from your GitLab Self-Managed instance to the Jira development panel, it is sent from your GitLab Self-Managed instance directly to Jira and not to GitLab.com. GitLab.com does not use the token to access data in your Jira project. Your GitLab Self-Managed instance uses the token to access the data.

For more information about the lifecycle events and payloads that GitLab.com receives, see the Atlassian documentation.

sequenceDiagram
accTitle: Dataflow of the GitLab for Jira Cloud app installed from the Atlassian Marketplace
accDescr: How GitLab.com handles lifecycle events when the GitLab for Jira Cloud app was installed from the Atlassian Marketplace

    participant Jira
    participant Your instance
    participant GitLab.com
    Jira->>+GitLab.com: App install/uninstall event
    GitLab.com->>-Your instance: App install/uninstall event
    Your instance->>Jira: Your development data

GitLab.com handling of branch creation

When you have installed the GitLab for Jira Cloud app from the Atlassian Marketplace, the links to create a branch from the development panel initially send the user to GitLab.com.

Jira sends GitLab.com a JWT token. GitLab.com handles the request by verifying the token and then redirects the request to your GitLab instance.

Access to GitLab through OAuth

GitLab does not share an access token with Jira. However, users must authenticate through OAuth to configure the app.

An access token is retrieved through a Proof Key for Code Exchange (PKCE) OAuth flow and stored only on the client side. The app frontend that initializes the OAuth flow is a JavaScript application that’s loaded from GitLab through an iframe on Jira.

The OAuth application must have the api scope, which grants complete read and write access to the API. This access includes all groups and projects, the container registry, and the package registry. However, the GitLab for Jira Cloud app only uses this access to:

• Display groups to link.
• Link groups.

Access through OAuth is only needed for the time a user configures the GitLab for Jira Cloud app. For more information, see Access token expiration.

Using a reverse proxy

You should avoid using a reverse proxy in front of your GitLab Self-Managed instance if possible. Instead, consider using a public IP address and securing the domain with a firewall.

If you must use a reverse proxy for the GitLab for Jira Cloud app on a GitLab Self-Managed instance that cannot be accessed directly from the internet, keep the following in mind:

• When you install the GitLab for Jira Cloud app from the Atlassian Marketplace, use a client with access to both the internal GitLab FQDN and the reverse proxy FQDN.
• When you install the GitLab for Jira Cloud app manually, use the reverse proxy FQDN for Redirect URI to set up OAuth authentication.
• The reverse proxy must meet the prerequisites for your installation method:
  • Prerequisites for connecting the GitLab for Jira Cloud app.
  • Prerequisites for installing the GitLab for Jira Cloud app manually.
• The Jira development panel might link to the internal GitLab FQDN or GitLab.com instead of the reverse proxy FQDN. For more information, see issue 434085.
• To secure the reverse proxy on the public internet, allow inbound traffic from Atlassian IP addresses only.
• If you use a rewrite or sub_filter directive with your proxy, ensure the proxy does not rewrite or replace the gitlab-jira-connect-${host} app key. Otherwise, you might get a Failed to link group error.
• When you select Create branch in the Jira development panel, you are redirected to the reverse proxy FQDN rather than the internal GitLab FQDN.

External NGINX

This server block is an example of how to configure a reverse proxy for GitLab that works with Jira Cloud:

server {
  listen *:80;
  server_name gitlab.mycompany.com;
  server_tokens off;
  location /.well-known/acme-challenge/ {
    root /var/www/;
  }
  location / {
    return 301 https://gitlab.mycompany.com:443$request_uri;
  }
}
server {
  listen *:443 ssl;
  server_tokens off;
  server_name gitlab.mycompany.com;
  ssl_certificate /etc/letsencrypt/live/gitlab.mycompany.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/gitlab.mycompany.com/privkey.pem;
  ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384';
  ssl_protocols  TLSv1.2 TLSv1.3;
  ssl_prefer_server_ciphers off;
  ssl_session_cache  shared:SSL:10m;
  ssl_session_tickets off;
  ssl_session_timeout  1d;
  access_log "/var/log/nginx/proxy_access.log";
  error_log "/var/log/nginx/proxy_error.log";
  location / {
    proxy_pass https://gitlab.internal;
    proxy_hide_header upgrade;
    proxy_set_header Host             gitlab.mycompany.com:443;
    proxy_set_header X-Real-IP        $remote_addr;
    proxy_set_header X-Forwarded-For  $proxy_add_x_forwarded_for;
  }
}

In this example:

• Replace gitlab.mycompany.com with the reverse proxy FQDN and gitlab.internal with the internal GitLab FQDN.
• Set ssl_certificate and ssl_certificate_key to a valid certificate (the example uses Certbot).
• Set the Host proxy header to the reverse proxy FQDN to ensure GitLab and Jira Cloud can connect successfully.

You must use the reverse proxy FQDN only to connect Jira Cloud to GitLab. You must continue to access GitLab from the internal GitLab FQDN. If you access GitLab from the reverse proxy FQDN, GitLab might not work as expected. For more information, see issue 21319.

Set an additional JWT audience

When GitLab receives a JWT token from Jira, GitLab verifies the token by checking the JWT audience. By default, the audience is derived from your internal GitLab FQDN.

In some reverse proxy configurations, you might have to set the reverse proxy FQDN as an additional JWT audience. To set an additional JWT audience:

1. In the upper-right corner, select Admin.
2. In the left sidebar, select Settings > General.
3. Expand GitLab for Jira App.
4. In Jira Connect Additional Audience URL, enter the additional audience (for example, https://gitlab.mycompany.com).
5. Select Save changes.