To connect Jira and GitHub, install the free GitHub for Atlassian app from the Atlassian Marketplace, then connect your GitHub organization. You need Jira site admin permission to install the app and GitHub organization owner permission to connect the org; often that’s two different people. After that, anything your team names with a Jira key (like PAY-142) in a branch name, commit message, or pull request title shows up in the work item’s development panel.
The steps below follow Atlassian’s Connect GitHub Cloud to Jira guide and Smart Commits reference, plus the GitHub for Atlassian Marketplace listing (listed as a free app), checked October 10, 2026.
Before you start
| You need | Why |
|---|---|
| Jira site admin | To install the app |
| GitHub organization owner | To connect the org and approve repo access |
| A decision on All repositories vs Only select repositories | “All” picks up new repos automatically; “select” means adding each new repo by hand |
| An agreed key convention | Nothing links unless people use the Jira key |
The app works with GitHub Cloud and GitHub Enterprise Cloud. GitHub Enterprise Server uses a separate setup path in Atlassian’s docs.
Step 1: Install GitHub for Atlassian
- In Jira, select Apps → Explore more apps.
- Search for GitHub for Atlassian.
- Select Get app → Get it now.
Step 2: Connect your GitHub organization
- After install, select Get started (or later: Apps → Manage your apps → GitHub for Atlassian).
- Select Continue → GitHub Cloud → Next, and sign in to GitHub.
- Find your organization and select Connect. You only see Connect if you’re an org owner.
- Not an owner? Choose Send them a link and ask them to connect and send it to an owner.
- If your org isn’t listed, install the Jira app on that GitHub org first, choosing All repositories or Only select repositories.
- Choose whether GitHub data should be available in Atlassian Rovo (search, chat, and agents). You can leave it off and the integration still works.
- Confirm the org appears under Apps → Manage your apps → GitHub for Atlassian.
You can connect more than one GitHub organization to the same Jira site from the same screen.
Step 3: Link your work with Jira keys
| Where | Example | What shows in Jira |
|---|---|---|
| Branch name | git checkout -b PAY-142-retry-webhooks | Branch in the development panel |
| Commit message | PAY-142 add retry on 503 | Commit linked to the work item |
| Pull request title | PAY-142 Retry failed webhooks | PR and its status |
You can also create a branch straight from a Jira work item, which pre-fills the key in the branch name. That one habit fixes most “why isn’t my PR showing up” complaints.
Step 4: Use Smart Commits (carefully)
Smart Commits let a commit message act on the work item:
| Command | Example | Effect |
|---|---|---|
#comment | PAY-142 #comment fixed the retry backoff | Adds a comment |
#time | PAY-142 #time 1h 30m tuned retries | Logs work (time tracking must be on) |
| Transition | PAY-142 #done #comment shipped | Moves the work item through that workflow transition |
The gotchas, all from Atlassian’s reference:
- The committer’s email must match exactly one Jira user with permission to do the action. Commits from a personal email won’t run commands.
- A transition silently fails if that transition has required fields or a screen. Keep Smart Commit transitions to simple ones.
- If two transitions start with the same word (Start Review, Start Progress), use the hyphenated full name, like
#start-review.
Many teams skip Smart Commit transitions entirely and let Jira automation move work items when a PR is opened or merged. It’s easier to debug.
Step 5: Add builds and deployments
The app can also send GitHub Actions workflow runs and deployments to Jira, so each work item shows whether its code reached staging or production. Atlassian documents this under “Link GitHub workflows and deployments to Jira.” It relies on the same Jira keys in branch names and commits, plus your deployment environments being set up in GitHub.
Connect new repositories later
If you chose Only select repositories, new repos aren’t added automatically. Go to Apps → Manage apps → GitHub for Jira → Configure, open the org’s … menu → Configure, then add the repo under Repository access in GitHub.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| No Connect button | You aren’t a GitHub org owner | Send the connect link to an owner |
| Org not in the list | Jira app not installed on that org | Install it on the org, then connect |
| New repo’s PRs don’t appear | “Only select repositories” was chosen | Add the repo under Repository access |
| Commits not linked | Key missing or lowercase in the message | Use the exact key, e.g. PAY-142 |
| Smart Commit did nothing | Email mismatch, missing permission, or required fields on the transition | Match commit email to Jira; simplify the transition |
| Data stopped syncing | IP allowlist on the GitHub org | Follow Atlassian’s IP allowlist workaround article |
If you’re deciding whether you need Jira at all next to GitHub, we compared Jira vs GitHub Projects and Linear vs GitHub Issues. For sprint workflows once the integration is running, see our Jira sprint planning guide.
Common questions
Is the GitHub for Jira app free?
Yes. GitHub for Atlassian is listed as a free app on the Atlassian Marketplace. You still pay for your Jira and GitHub plans.
Who needs to set up the Jira GitHub integration?
A Jira site admin installs the app, and a GitHub organization owner connects the organization and approves repository access.
Can I connect multiple GitHub organizations to one Jira site?
Yes. After connecting the first organization, you can add another from the same setup screen.
Does it work with GitHub Enterprise?
GitHub Enterprise Cloud uses the same steps. GitHub Enterprise Server has a separate setup path in Atlassian’s documentation.
Why aren’t my commits showing up in Jira?
Usually the Jira key is missing or mistyped in the branch, commit, or PR title, or the repository wasn’t included when the organization was connected.
Steps checked against Atlassian Support and the Atlassian Marketplace on October 10, 2026. Menu names in Jira change fairly often, so labels may differ slightly.
Sponsored
