Integrate Jira with GitHub: The Setup, and the Conventions That Make It Work

Install the GitHub app for Jira, authorise your organisation, and development activity starts appearing on work items — but only for branches, commits and pull requests that mention the issue key. The integration is a string match, and everything follows from that.

The connection itself is a few clicks and is well covered by the vendor documentation. What is not covered is the part that determines whether the integration is useful in six months: the conventions your team adopts, and the automation you choose not to enable.

Table of contents

• The setup
• The convention that makes it work
• Automating transitions, carefully
• What the integration cannot do for you
• How this fits the rest of the stack
• FAQ

The setup

For GitHub Cloud, install the GitHub for Jira app from the Atlassian marketplace, connect it to your GitHub organisation, and select which repositories to share. Jira then performs an initial backfill of existing history, which can take a while on a large organisation and is worth starting before you need it.

GitHub Enterprise Server takes a longer path — a GitHub app created on your instance, connected through Jira, with network access allowed in both directions. If your GitHub organisation restricts API access by address, add Atlassian’s ranges to the allowlist or the connection will appear to succeed and then quietly fail to sync.

The permissions the app requests are broad enough to be worth reading rather than clicking through: repository contents, pull requests, deployments and webhook events. On an organisation with sensitive repositories, share selectively rather than granting access to everything.

Once connected, a work item grows a development panel showing branches, commits, pull requests, builds and deployments linked to it.

The convention that makes it work

Everything hinges on the issue key appearing in the right places. No key, no link, and no error to tell you.

# Branch name -- the key at the start
git checkout -b PROJ-1234-add-webhook-retries

# Commit message -- the key first, then a real description
git commit -m "PROJ-1234 Retry webhook delivery with exponential backoff"

# Pull request title
# PROJ-1234 Retry failed webhook deliveries

Two habits make this stick without anyone having to remember.

Create branches from Jira. The development panel has a create-branch action that names the branch correctly and links it immediately. It is faster than typing the key by hand and it cannot be typed wrong.

Enforce it in CI, so a missing key is caught at the point it matters rather than discovered during a release.

name: Check issue key
on: [pull_request]

jobs:
  key:
    runs-on: ubuntu-latest
    steps:
      - name: Require a Jira key in the PR title
        run: |
          echo "$TITLE" | grep -qE '^[A-Z]+-[0-9]+' || {
            echo "PR title must start with a Jira issue key, e.g. PROJ-1234"
            exit 1
          }
        env:
          TITLE: ${{ github.event.pull_request.title }}

Use an environment variable rather than interpolating the title directly into the script — a pull request title is user-controlled text, and injecting it into a shell command is a genuine vulnerability, not a style preference.

Automating transitions, carefully

Smart commits let a commit message move a ticket, log time, or add a comment:

git commit -m "PROJ-1234 #comment Retry logic added, needs load testing"
git commit -m "PROJ-1234 #time 3h Debugging the delivery queue"
git commit -m "PROJ-1234 #close Fixed in this release"

This is where teams tend to overreach. A rule that moves a ticket to Done when a pull request merges sounds tidy and is usually wrong: merged is not deployed, and deployed is not verified. A ticket marked Done that is still sitting on main unreleased makes the board lie, and a board that lies stops being consulted.

The automation worth having is the narrow, factual kind:

• Branch created moves the ticket to In Progress. This is reliably true and saves a manual step nobody enjoys.
• Pull request opened moves it to In Review. Also reliably true.
• Pull request merged adds a comment, and does not change the status.
• Deployment to production moves it to Done — if, and only if, you actually report deployments to Jira.

That last one is what deployment reporting is for. With deployment events flowing from Actions, the board reflects what is live rather than what is merged, and the question is this in production yet has an answer that does not require asking anyone.

What the integration cannot do for you

Worth being clear about, because the setup guide implies more than it delivers.

• It does not keep the board accurate. It reports git activity. If people work on things without tickets, or leave tickets open after shipping, the board is wrong and the integration faithfully reports nothing about it.
• It does not link work with no key. A hotfix committed straight to main at 2am has no key and never appears. This is exactly the work you most want recorded.
• It does not resolve the two-systems problem. Discussion still splits between pull request review comments and ticket comments, and the integration surfaces links rather than merging conversations.
• The backfill is historical, not retroactive. Commits that never mentioned a key stay unlinked forever.

The honest framing: this is a reporting integration. It makes existing discipline visible. It does not create discipline, and a team that was not tracking work carefully before will have the same problem afterwards, now with a dashboard.

Where it genuinely earns its keep is the question that gets asked constantly and answered badly — which change is in which environment. When branch, pull request and deployment events all land on the ticket, that becomes a glance instead of an investigation.

How this fits the rest of the stack

The most valuable half of this integration is the deployment half, and it is the half most teams never wire up. A ticket that shows the branch, the pull request, and the environment the change actually reached answers the question people keep asking. A ticket that stops at merged does not.

That requires deploys that are discrete, observable events rather than a script someone runs. On RunxBuild, a merge builds the service or static site from your GitHub repository, with the build log and the runtime logs in one place and a rollback to the previous deploy when something goes wrong — so there is a specific deploy, at a specific time, with a specific result to report against. Managed MySQL and Postgres sit alongside on private networking. To price a service, its database and storage per environment, the RunxBuild hosting calculator lists them as separate line items.

Useful related references:

• The Jira REST API: Authentication, Search, and the Pagination Trap
• Git vs GitHub vs GitLab: One Is a Program, Two Are Companies
• Undo Commit on GitHub: What You Can Do in the Browser and What Needs the Terminal
• Deploying from GitHub on RunxBuild

FAQ

How do I connect Jira to GitHub?

Install the GitHub for Jira app from the Atlassian marketplace, authorise your GitHub organisation, and choose which repositories to share. Jira backfills existing history afterwards, which takes a while on a large organisation. GitHub Enterprise Server needs a manually created GitHub app and network access allowed in both directions.

Why is my branch not showing up on the Jira ticket?

Because the issue key is not in the branch name, commit message or pull request title. The integration is a string match on that key, and there is no error when it is absent. Creating the branch from the Jira development panel names it correctly, and a CI check on the pull request title catches the rest.

Should merging a pull request close the Jira ticket?

Usually not. Merged is not deployed and deployed is not verified, so a ticket marked Done while the change sits unreleased on main makes the board inaccurate. Move to Done on a production deployment event instead, and have the merge add a comment rather than change the status.

What are smart commits?

Commands embedded in a commit message that act on the referenced issue — adding a comment, logging time, or transitioning the ticket. They are useful for comments and time logging. Be conservative with transitions, since a commit message is a poor place to encode process decisions the whole team depends on.

Does the integration work with GitHub Enterprise Server?

Yes, with more setup. You create a GitHub app on your instance and connect it through Jira, and both systems need network access to each other. If your organisation restricts API access by IP, add Atlassian’s ranges to the allowlist — otherwise the connection appears to succeed and then silently fails to sync.