GitLab Jira Integration: The Two Halves, and Which One You Actually Need

GitLab’s Jira support is two features with one name. The Jira issues integration brings Jira into GitLab; the Jira development panel pushes GitLab activity into Jira. You configure them separately, and most teams only want the second.

The reason this integration has a reputation for being fiddly is that people configure one half and expect the behaviour of the other. Knowing which half you are setting up removes most of the frustration before you start.

Table of contents

• The two halves
• Setting up the Jira issues integration
• Setting up the development panel
• Making it work: issue keys everywhere
• When it appears broken
• How this fits the rest of the stack
• FAQ

The two halves

Jira issues integration works inside GitLab. Once configured, GitLab detects Jira issue keys in commit messages and merge requests, turns them into links, and can close Jira issues from a commit. It also adds a Jira issues list to the GitLab project sidebar.

Jira development panel works inside Jira. It populates the Development section of a Jira issue with the branches, commits, merge requests, builds, and deployments that reference that issue key. This is the one that makes a Jira ticket show you the code.

Which you need depends on where your team spends its day. If people live in Jira and want to see engineering progress without asking, you want the development panel. If people live in GitLab and want Jira context without switching tabs, you want the issues integration. Plenty of teams end up with both.

They also have different setup paths. The issues integration is configured entirely in GitLab project settings. The development panel requires an app installed on the Jira side, which usually means involving a Jira administrator.

Setting up the Jira issues integration

This half is configured per project, or once at the group or instance level to apply everywhere.

1. In Jira, create an API token from your Atlassian account settings. For Jira Cloud, the username is the account email address and the password field takes the token.
2. In GitLab, open the project and go to Settings, then Integrations, and choose Jira.
3. Set the web URL to your Jira site.
4. Enter the email address and API token.
5. Choose which issue transitions should happen when a commit closes an issue.
6. Use the Test settings button before saving. This is the step people skip, and it is the difference between finding a credential problem now and finding it in a week.

For Jira Data Center or Server, use a username and password rather than an API token, and make sure the account has browse and transition permissions on the relevant projects.

Configuring at the group level is worth doing if you have more than a handful of projects. Group-level settings cascade to every project underneath, and individual projects can still override when they need to.

Setting up the development panel

For Jira Cloud, this uses the GitLab app from the Atlassian Marketplace.

1. Install the GitLab app for Jira Cloud from the Atlassian Marketplace into your Jira site.
2. In Jira, go to Settings, then Apps, then Manage apps, find the GitLab app and select Get started.
3. Select Add namespace and enter your GitLab namespace - the group portion of your project URL, not the project name.
4. Authorise the connection when GitLab prompts.

For Jira Data Center or Server, the path is different: you use the Jira DVCS connector, which Atlassian maintains rather than GitLab. It polls rather than receiving webhooks, so updates arrive on a delay.

For self-managed GitLab connecting to Jira Cloud, there is a separate app configuration where GitLab acts as the OAuth provider. That path needs your GitLab instance to be reachable from Jira, which is the detail that catches teams running GitLab behind a VPN.

Making it work: issue keys everywhere

Neither integration does anything without Jira issue keys in your Git activity. The key is the project prefix plus a number, and GitLab scans for it in branch names, commit messages, and merge request titles and descriptions.

# Branch name
git switch -c PROJ-451-fix-session-expiry

# Commit message
git commit -m "PROJ-451: expire sessions on password change"

# Closing an issue from a commit
git commit -m "Closes PROJ-451: expire sessions on password change"

Case matters. A lowercase key will not match; it must be uppercase exactly as Jira has it. This is the most common reason a correctly configured integration appears to do nothing.

For build and deployment information to reach the Jira deployments timeline, your CI configuration needs a job with an environment defined. Without it, GitLab has no deployment to report.

deploy_production:
  stage: deploy
  environment:
    name: production
    url: https://app.example.com
  script:
    - ./deploy.sh
  only:
    - main

The most reliable way to enforce keys is a push rule requiring them in commit messages, available on paid GitLab tiers. Without that, a commit-message hook distributed to the team is the practical substitute - imperfect, since hooks are local, but better than relying on memory.

When it appears broken

The failure modes are few and repeat, so a short checklist resolves most reports.

• Nothing links at all. Run Test settings in GitLab. An expired API token is the most common cause, and it fails silently rather than raising anything visible.
• Links appear, panel is empty. You configured the issues integration but not the development panel. They are separate; doing one does not do the other.
• Some issues update, others do not. Check case on the issue keys, and check that the Jira account used by the integration has permission on that Jira project. Permissions are per-project in Jira, and a new project will not be covered by an older integration user.
• Commits do not close issues. The configured transition must exist in that Jira project’s workflow. Workflows differ per project, so a transition name that works in one may not exist in another.
• Nothing arrives on a self-managed instance. Jira Cloud has to reach your GitLab instance. Behind a firewall or VPN, it cannot.
• Data Center feels slow. The DVCS connector polls on a schedule rather than receiving events. A delay of minutes is expected behaviour, not a fault.

One structural note worth making before you invest heavily. This integration ties your issue tracker to your source host, and both ends have to keep working. When it breaks, the symptom is usually silence rather than an error, which means nobody notices until someone asks why a ticket has no commits. Treat the connection as something to check periodically, not something to configure once and forget.

How this fits the rest of the stack

Once the tracker knows which commits shipped, the next question is where they shipped to. Push a repo to RunxBuild and you get a build log, a live route, runtime logs, and rollback to the previous deploy - the deployment half of the story that the Jira panel is trying to summarise. The RunxBuild hosting calculator puts the service, the managed Postgres, and the bandwidth on one page so the environment behind those tickets has a number attached.

Useful related references:

• Integrate Jira with GitHub: The Setup, and the Conventions That Make It Work
• The Jira REST API: Authentication, Search, and the Pagination Trap
• GitLab vs Bitbucket: CI Depth Against Atlassian Integration
• Services on RunxBuild

FAQ

What is the difference between the Jira issues integration and the development panel?

The issues integration works inside GitLab - it links Jira keys in commits and merge requests and can close Jira issues. The development panel works inside Jira, populating the Development section of an issue with branches, commits, merge requests, and deployments. They are configured separately, and setting up one does not enable the other.

Why is my GitLab Jira integration not working?

Check four things in order: use Test settings in GitLab to catch an expired API token, confirm the issue keys are uppercase and match Jira exactly, verify the integration account has permission on that Jira project, and confirm the transition you configured actually exists in that project’s workflow.

Do I need a Jira admin to set this up?

For the issues integration, no - it is configured in GitLab project settings with an API token you can create yourself. For the development panel on Jira Cloud, yes, because it requires installing the GitLab app from the Atlassian Marketplace, which needs Jira administrator rights.

How do I close a Jira issue from a GitLab commit?

Include a closing keyword and the issue key in the commit message. The transition that runs is configured in the GitLab Jira integration settings, and it must be a transition that actually exists in that Jira project’s workflow.

Does this work with self-managed GitLab?

Yes, but the setup differs. Self-managed GitLab connecting to Jira Cloud uses a separate app configuration where GitLab acts as the OAuth provider, and your instance must be reachable from Jira. If GitLab sits behind a VPN or firewall, the connection cannot be established.