GitLab and Jira integration

How the GitLab and Jira integration works and which option to choose

If your team runs self-managed GitLab and wants Jira to show code activity or to link issues, you have two different mechanisms to choose from: the Jira issues integration and the development panel. The Jira issues integration lets GitLab reference Jira issues from merge requests, commits and issues, so a Jira key in a commit message or merge request title can connect the two tools. The development panel is a Jira-side view that displays branches, commits, merge requests and pipeline status for a Jira issue. They solve different problems, so the choice depends on which tool your team uses as the place of record and where developers need to see the link.

Before you configure either option, confirm the exact features, required permissions and setup steps against GitLab's current Jira documentation for the version you run, and against the Jira product you use, Jira Cloud or Jira Data Center. The supplied references for this page do not include Jira-specific documentation, so do not assume that a given feature, connection method or field behaves the same across GitLab versions or Jira deployment types. Ask your GitLab administrator which integration settings are enabled at the instance or group level, because those defaults can limit what a project is allowed to connect.

Plan the decision around project data visibility. Connecting a project to Jira can expose project names, commit messages, branch names, merge request titles and pipeline results to anyone who can view the linked Jira issues, so review which GitLab projects are sensitive before you link them. Ask your security and compliance team what Jira users are allowed to see, check whether any project names or commit text contain confidential information, and test the link with a non-sensitive project before rolling it out. Record the choice of mechanism and the visibility review in your change records so that later upgrades of either tool do not silently change what is shared.

What you need before connecting GitLab to Jira

The Jira connection depends on decisions made before anyone opens a settings page: which GitLab edition and version you run, whether Jira is Cloud or Data Center, and whether the two systems can reach each other. Confirm each item below against the current GitLab and Jira documentation rather than assuming defaults.

GitLab version and edition

Record the exact installed GitLab version and whether the instance is Free, Premium or Ultimate. Confirm in the current GitLab documentation which Jira features are available on your edition and version, since feature availability can change between releases. Also check whether your version is on a supported maintenance line, because the upgrade path affects which integration behavior you can rely on. Note the result in your implementation record so it can be checked again after upgrades.

Jira deployment and version

Determine whether the target is Jira Cloud or Jira Data Center, and record its exact version. The configuration screens, authentication options and supported connection methods differ between the two, so instructions written for one may not apply to the other. Confirm the current Jira documentation for your deployment before choosing a connection method, and check whether your Jira site is reached through a proxy or load balancer that changes the address GitLab must call.

Jira account and permissions

The connection is created with a Jira account, and that account's permissions decide what GitLab can read and write. Use a dedicated service account where your policy allows it, rather than a personal login, so the connection survives staff changes. Confirm which project permissions and global permissions Jira requires for the actions you plan, such as reading issues, transitioning them or creating links, and grant no more than those. Record who owns the account and how its credentials are rotated.

Network reachability in both directions

GitLab must reach the Jira base URL to call its API, and Jira must be able to reach GitLab if you use features that depend on inbound calls. Confirm outbound rules from the GitLab host or its egress proxy, and any firewall or allowlist between the two networks. For air-gapped or restricted networks, check whether the Jira integration needs external connectivity at all. Test from the GitLab host itself, not from an administrator workstation, because the two may route differently.

Certificate trust for private CAs

If Jira is served with a certificate issued by a private certificate authority, GitLab must trust that CA or the connection will fail during validation. Add the CA certificate to the GitLab trust store according to the current GitLab documentation for custom certificates, and verify the chain from the GitLab host before configuring the integration. Do not disable certificate verification to get past an error, because that removes protection for the Jira credentials sent over the connection.

Configuring the Jira connection in the right order

This sequence takes a self-managed GitLab instance from a blank Jira connection to a tested, scoped link that teams can see in both tools. Each step closes with a check you can record, so a wrong setting is caught before project data becomes visible in Jira.

Confirm prerequisites before changing settings
Confirm whether you run Jira Cloud or Jira Data Center, because the authentication method and connection details differ between them. Check that your GitLab instance can reach the Jira address over the network path you plan to use, that your GitLab version and edition support the integration you chose, and that an administrator in both systems is available. Decide which GitLab groups and projects are in scope. This step is done when the list is written down, reviewed by the Jira administrator and checked against the current GitLab and Jira documentation for your versions.
Create a dedicated Jira service account
Ask the Jira administrator to create a service account used only by GitLab, not a personal account, so connection activity and later access reviews stay traceable. Grant it access only to the Jira projects that will be linked, with the minimum permissions the integration documentation requires for reading issues and handling links. Avoid site-wide administrator rights. Check by signing in as the account in a test session and confirming it sees the in-scope projects and nothing outside them.
Generate and store the connection credential
Create the credential type that the GitLab documentation specifies for your Jira deployment, under the service account. Confirm expiry and rotation rules with your security team before first use. Store the value in your approved secrets manager or the protected configuration your GitLab administrators use, and keep it out of tickets, chat and shared runbooks. Record its owner and next rotation date. Check that the credential appears in your secrets inventory with an owner and a scheduled review, and that no copy exists outside that store.
Configure the connection at instance level
As a GitLab administrator, open the instance-level Jira integration settings and enter the Jira address and the credential details the documentation requests for your deployment type. Leave broad enablement for later steps so the instance defaults stay limited to what you have approved. Use the connection test in the settings, if your version offers one. Check that the test returns a successful result and that the saved settings show the connection as active at instance level before you continue.
Set group and project inheritance deliberately
Decide which groups inherit the instance connection and which projects override it, based on the scope from the first step. Inheritance keeps configuration consistent across teams, while overrides suit projects that link to a different Jira site or key scheme. Apply settings to in-scope groups first and leave out-of-scope groups disabled. Check by opening one inheriting project and one overriding project and confirming each shows the expected source of its settings, with no unintended project showing an active connection.
Limit linked projects and issue keys
Restrict the connection to the Jira projects agreed in the first step, and confirm which project keys GitLab will recognize in commit messages, branch names and merge request titles. Overlapping or reused keys can link work to the wrong ticket, so compare each key against the Jira project list before enabling it. Confirm whether the issues integration and the development panel are both enabled and what each one exposes, because they show different information. Check with a review that lists every enabled key and maps each to exactly one in-scope Jira project.
Run an end-to-end test on a sample project
Use a non-production GitLab project and an issue in a test Jira project. Create a branch or commit message containing the test issue key, then open a merge request that references it. Confirm the link appears on the Jira issue. If your configuration posts updates back to Jira, make a state change in GitLab and confirm it arrives. Check that the Jira issue shows the linked commit or merge request in its development information and that event times match the test actions you performed.
Record the configuration and hand over
Write down the final settings, the service account owner, the credential location and rotation date, the in-scope projects and keys, and the test evidence. Give the Jira and GitLab administrators a copy, and schedule a review of account permissions and linked projects. Route any future scope change through the same record. Check that the record is stored with your change documentation and that both administrators confirm in writing that it matches the live configuration.

Jira Cloud or Jira Data Center: what changes for the setup

With Jira Cloud, Atlassian hosts the Jira application and runs its upgrades, so your team does not schedule Jira version changes. The GitLab side still needs a credential that Jira accepts, and the access model is set by Atlassian's cloud account and product administration rather than by a server you operate. Your decisions center on which account or service identity makes the connection, how that identity is scoped to the projects you want linked, and who is allowed to change the settings later.

Authentication: Confirm which credential type your Jira Cloud site accepts for the GitLab integration, and whether a dedicated service account is preferred over a personal user.
Administration: Decide who holds the Jira administrator role needed to create the connection, and who owns it when that person leaves.
Network path: GitLab must reach the Jira Cloud endpoints from your network. Check any outbound proxy, egress allowlist or DNS policy that applies to a self-managed GitLab instance.
Certificates: Public certificates from the cloud provider are usually trusted by default, but confirm that your egress inspection devices do not break the connection.
Upgrades: Atlassian owns Jira upgrades, so your planning concerns API or behavior changes announced by the vendor rather than your own version schedule.

Before you build, confirm the exact authentication options and supported versions for your site in the GitLab documentation for Jira integration.

Which GitLab data becomes visible in Jira and which Jira data flows back

This table maps the main data objects exchanged between self-managed GitLab and Jira, showing the likely direction, where each item appears and what to confirm. Read it as a checklist for your own version and integration type, not as a settled list. The main takeaway is that visibility depends on project permissions and on whether you use the Jira issues integration or the development panel.

Data object	Direction	Where it appears	What to confirm
Jira issue keys in commits	GitLab to Jira	Jira issue development panel, linked to the issue	Key format matches your Jira project keys and the integration is enabled for that GitLab project
Issue keys in branch names and merge requests	GitLab to Jira	Development panel on the Jira issue, listing branches and merge requests	Whether your integration type links branches and merge requests, and which pattern it matches
Commit and pipeline activity	GitLab to Jira	Development panel summary on the Jira issue	Which event types your integration type sends and whether pipeline status is included
Jira issue status or transitions	Jira to GitLab, or not supported	Depends on the integration; not a general two-way sync	Whether your GitLab version supports transition mapping, and in which direction, in the current integration documentation
Jira issue details in GitLab	Jira to GitLab	GitLab issue or merge request views, if the Jira issues integration is used	Which fields are shown, and whether comments or attachments are displayed or only linked
Users and identities	Both directions	Author and assignee names on linked items in each tool	How GitLab usernames map to Jira accounts, and whether email addresses are exposed to users on the other side
Project data visibility	Both directions	Any linked item a user can open from the other tool	That Jira users and GitLab users hold the permissions they need, since access is checked at the source and not copied

Securing the connection between GitLab and Jira

A Jira connection gives a service account read and write access to project data across two systems, so its scope, credential and audit trail deserve the same care as any other integration account. The cards below cover the controls that keep that connection narrow, verifiable and easy to revoke. Apply them in a test environment first, then roll them out gradually and verify each change before moving on.

Dedicated least-privilege Jira account

Create a separate Jira user for the integration instead of reusing a personal account or an administrator. Grant it only the project permissions needed to read issues and, where you enable it, write comments or transitions in the projects you link. A personal account disappears when its owner leaves, and a broad account turns a leaked token into a wider incident. Confirm the exact permissions with the Jira and GitLab documentation for your deployment type before granting them.

Credential kept in integration settings

Enter the Jira API token in the GitLab integration settings, never in .gitlab-ci.yml, project variables that anyone with developer access can read, or repository files. Set the token's lifetime according to your rotation policy, record its owner and creation date, and rotate it on a schedule and whenever a team member with access leaves. Confirm with your security team where tokens are stored at rest on your instance and who can read them through the database or backups.

Limit which projects are linked

Only link projects whose Jira activity is meant to be visible to the Jira audience. Linking a private GitLab project can expose its branch names, merge request titles and commit messages to people who can see the Jira project. Start with a short list of approved projects, and review the list when a new project is created or an existing one changes visibility. Pair this with the instance and group defaults so new projects do not inherit a link automatically.

TLS and certificate trust

Connect to Jira only over HTTPS, and confirm that GitLab trusts the certificate chain of your Jira Data Center server or your proxy. Disabling certificate verification to make a connection work removes the protection the token depends on. If your Jira instance uses an internal certificate authority, install that root in the GitLab trust store through the documented configuration and test the connection before enabling it for projects.

Audit logging on both sides

Review the audit trail in GitLab for who created, changed or disabled the Jira integration, and the Jira audit log for the service account's logins, permission changes and API activity. Forward both to your central log platform so that an unexpected action in either system can be correlated with the other. Confirm which events each product records and how long they are retained in your deployment before you rely on them for investigations.

Review who can change integrations

Decide which roles may enable, edit or disable the Jira integration, and keep that list short. Changing the Jira URL or swapping the account can redirect project data to a different Jira instance, so treat these changes like other configuration changes that need a second person to review them. Use the integration allowlist and instance settings to limit what project maintainers can enable. The GitLab hardening guidance covers the wider configuration review that should surround these settings.

How to test the link before teams rely on it

Run the test on a non-production or pilot Jira project before any team depends on the link. Pick a test project with a few disposable issues and, if your Jira is Cloud or Data Center, confirm which connection method your GitLab version supports for that deployment. The goal is to observe each behavior directly rather than assume it. Treat every check below as something to run and record, not as a guaranteed outcome, because results depend on your GitLab version, your Jira edition and how the integration was configured. Write down the GitLab version, the Jira product and the account used for the connection so the results can be repeated after an upgrade.

Create a test issue in the pilot project and note its issue key. Then create a branch whose name or commit message includes that key, push a commit, and open a merge request that references the key in its title or description. Check whether the activity appears on the Jira issue in the development information area, and whether it updates as the merge request is reviewed and merged. Also confirm that the link does not appear for a key that does not exist. Repeat the exercise with the issue transition setting you plan to use, if you intend commits or merges to move issues, and verify the resulting status in Jira before enabling it for real projects.

Test access boundaries with a user who has no permission on the GitLab project and no permission on the Jira project. Confirm that the Jira side shows no GitLab data they should not see, and that the GitLab side does not expose Jira content beyond what the connected account can read. Then rotate the credential or access token used by the integration, following your own rotation procedure, and confirm that the link still works, that failed authentication produces a visible error and that the rotation runbook names who updates the stored secret. A link that breaks silently at rotation is one of the most common operational surprises, so record the steps needed to restore it.

Common Jira integration failures and how to isolate them

This table pairs the failures teams most often report when linking self-managed GitLab to Jira with a likely cause and a first check for each. Read it from the top: start with the connection test, then work through reference, visibility and network symptoms. Each cause is something to verify in your own environment, not a confirmed defect in either product.

Symptom	Likely cause to check	First check
Connection test fails in the Jira integration settings	Wrong Jira URL, a mismatch between Jira Cloud and Data Center settings, or a username and token pair that Jira does not accept	Confirm the base URL, the deployment type selected in GitLab, and that the account used can log in to Jira directly
Issue keys in commits or merge requests do not link to Jira	Jira project key is not enabled for the integration, or the reference format does not match the key in Jira	Check the project key list in the integration settings and test with a commit message that uses an exact key such as PROJ-123
Jira shows no development activity for GitLab work	Development panel not connected for the Jira project, or the GitLab connection was made to a different Jira site than the one holding the issues	Compare the Jira site URL in GitLab with the site where the issue lives, then confirm the app or connection is authorized for that project
Jira shows activity from private GitLab projects unexpectedly	The Jira connection was authorized by a user or account with broad read access, so project-level visibility in GitLab is wider than expected	Review which GitLab account authorized the link and which projects that account can read, then confirm the connection scope in both systems
Integration stops working after a token or password change	Expired or revoked personal access token, or a service account whose credentials were rotated or disabled	Check the token expiry and status for the account used, and confirm the account is still active in Jira and GitLab
Certificate errors when connecting to a private Jira Data Center	Jira uses an internal certificate authority that GitLab does not trust, or the chain is incomplete	Verify the certificate chain from the GitLab host with standard TLS tools and confirm the internal CA is installed where GitLab expects it
Requests from GitLab to Jira time out or are refused	A firewall, proxy or egress rule blocks the path from the GitLab host or Sidekiq workers to the Jira endpoint	Test HTTPS connectivity from the GitLab host itself, check proxy settings, and review egress rules on both sides of the route
Some updates reach Jira and others never arrive	Intermittent network path issues, or a rate or queue backlog on the GitLab side that delays background jobs	Check GitLab background job health and logs for the integration over the same time window as the missing updates

Questions teams ask before connecting GitLab to Jira

What does a GitLab and Jira integration cost, and what drives the price?

The cost is mostly the time of the people doing the work, so it depends on scope rather than on any license fee for the integration itself. Scoping, configuration, testing and handover are the one-time parts. Ask for a quote that separates who is paid for each: discovery of your Jira project keys and workflows, creating the service account and credentials, setting the project-level integration in GitLab, testing with sample issues and merge requests, and documenting the result for your team. Recurring costs come from keeping both systems current: Jira and GitLab upgrades, credential rotation and checks after workflow changes. GitLab publishes a new minor release each month and a required upgrade stop every few releases, so budget for those cycles. Ask the provider to state which of these items are fixed and which are charged as time.

How long does it take to connect GitLab to Jira?

Duration depends on how many projects, workflows and Jira instances are involved, so ask for a timeline in the written scope rather than relying on a general figure. A single project with one Jira site and clear issue keys is usually simpler than a group-wide rollout across several Jira projects with different workflows. Time also depends on how quickly your Jira administrator can provide access and approvals, and on whether test projects already exist. Ask the provider to break the schedule into discovery, configuration, testing and handover, and to name the milestones where your team must sign off.

What must our team provide before the integration work starts?

Plan for four things before work begins. First, Jira administrator access or a named administrator who can create the connection and approve permissions. Second, a dedicated service account in Jira with only the permissions needed to read and transition the selected projects, plus an API token or credential that your security team approves. Third, one or more Jira test projects where issues can be created and moved without affecting production work. Fourth, a named owner on your side who makes decisions about workflow mapping, which projects are in scope and who receives access. Confirm the exact permission set with Jira documentation and your own security policy, because it differs between Cloud and Data Center.

Can our internal team set up the GitLab and Jira integration alone?

Often yes, for a small scope. A team that already runs both self-managed GitLab and Jira can configure the Jira issues integration or the development panel by following the GitLab documentation, provided it has the Jira admin rights and a test project. The harder parts are decisions, not clicks: which Jira projects are linked, how issue keys map to GitLab projects, what data Jira should display and who owns the credential afterwards. Outside help is most useful when the scope spans many projects, when Jira is Data Center behind a restricted network, or when your auditors will ask for evidence of the configuration. Whichever path you choose, document the decisions so the next administrator can operate the integration.

Do the Jira Cloud and Jira Data Center paths differ enough to change the plan?

Yes, the plan changes in several places, so confirm the path before scoping. Jira Cloud and Jira Data Center use different authentication methods and administration models, and the network path between your self-managed GitLab and Jira may differ. For Data Center, check whether your GitLab instance can reach the Jira server, whether a proxy or firewall rule is needed, and how certificates are managed. For Cloud, check API token ownership and who manages the site. The GitLab integration documentation describes the settings for each, and the Jira vendor documents the authentication options. Ask your provider to list the differences in the written scope and to test the connection in your own environment rather than assuming equivalence.

Does the integration require a specific GitLab tier?

Confirm this in the GitLab pricing page and the feature documentation for the version you run, rather than assuming. The GitLab pricing page lists three tiers for self-managed installations: Free at 0 US dollars, Premium at 29 US dollars per user per month billed annually, and Ultimate, which is custom priced. The page lists advanced CI/CD and priority support for Premium, and application security, supply chain and compliance features for Ultimate, but it does not settle which Jira integration features sit in which tier. Check the Jira integration page in the GitLab documentation for your release, and ask your provider to record the tier requirement for each feature in the written scope. Include the tier decision in the quote because it affects licensing cost.

What does the Jira integration expose to people who can see the Jira project?

Anyone with access to the linked Jira project can see the data the integration sends or displays, so confirm this before go-live. Depending on the feature you choose, Jira may show links to GitLab merge requests, branches, commits and pipeline status, or GitLab may show Jira issue references and titles. Review which GitLab projects and branches are connected, whether private project names or internal branch names appear, and who holds Jira permissions. Set the Jira permissions and GitLab project visibility together, and test with a restricted user before rollout. This review is also useful evidence for your access control records.

How DeployOpen scopes, builds and supports the GitLab and Jira integration

DeployOpen plans and implements self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks, and that includes linking self-managed GitLab with Jira. Engagements are fixed-scope, so the choice between the issues integration and the development panel is settled in writing before any configuration starts.

How we scope

Confirm whether you run Jira Cloud or Jira Data Center, since setup and authentication differ between them
Record which GitLab tier you run and which Jira features the chosen integration needs before work begins
Agree in writing which projects, groups and Jira sites are in scope and which project data may appear in Jira
Ask for the scope, deliverables and timeline in writing so the quote follows directly from what is covered

How we build

Configure the chosen integration at instance, group or project level, following your inheritance and override model
Test issue key linking, merge request references and commit references against a sample project before rollout
Verify which GitLab data becomes visible in Jira and confirm it matches your access and disclosure rules
Document each configuration setting, credential and permission so the integration can be reproduced and audited

How we hand over

Deliver a written configuration record covering settings, service accounts, scopes and the projects they reach
Walk your administrators through troubleshooting for failed connections, missing links and permission errors
Provide a verification checklist your team can rerun after GitLab or Jira upgrades
Confirm ownership of tokens and credentials, including the rotation steps your team will follow

How we support

Review the integration after each GitLab upgrade, since release notes can change integration behavior
Keep an eye on Jira API or authentication changes that could break the connection in your environment
Offer ongoing support, upgrades and testing as a retainer if you want continued coverage after handover
Re-scope in writing when new projects, Jira sites or features need to join the integration