Connect Jira to GitHub: A Step-by-Step Integration Guide
Need a Jira connect to GitHub guide? Learn how to link code activity to issues and avoid missed updates. Read now for the step-by-step setup.
Connecting Jira to GitHub lets your team see code activity alongside the Jira issues it relates to. Without that link, developers may update branches and pull requests while project managers chase progress in chat or status meetings. Important work can look stalled even when code is moving.
That gap creates avoidable confusion: someone may merge a pull request without linking it to the right issue, or a team may grant broader repository access than necessary. The good news is that Jira Cloud and GitHub can share development activity through Atlassian’s GitHub for Jira app. Here’s how to set up the connection, link work correctly, and troubleshoot common problems.
How to connect Jira to GitHub
For Jira Cloud, install Atlassian’s GitHub for Jira app, authorize the GitHub organization, and select the repositories Jira should monitor. Then include Jira issue keys in branch names, commit messages, and pull request titles so development activity can be associated with the right issue.
Before you begin, confirm that you have Jira site administrator access and permission to install GitHub apps for the organization. This guide covers Jira Cloud; Jira Data Center may use a different integration and configuration path.
- Check your access. Ask a Jira site administrator to confirm you can install apps. In GitHub, confirm an organization owner or app manager can authorize the integration and grant access to the intended repositories.
- Install GitHub for Jira. In Jira, open the apps area and find GitHub for Jira in Atlassian Marketplace. Review the app details, then choose the installation option available for your site.
- Authorize GitHub. Follow the setup prompts to connect a GitHub account or organization. Review the requested permissions before approving access. If GitHub requires an organization owner to approve the app, ask that person to complete the authorization.
- Choose repositories. Select all repositories or only the ones your team needs Jira to track. For example, a team working on the
storefront and checkout-api repositories can grant access to those repositories without connecting unrelated projects.
- Confirm the connection. Return to Jira’s app settings and check that the GitHub organization and selected repositories appear as connected. If the app reports that approval is pending, ask the organization owner to review the request in GitHub.
- Add Jira issue keys to development work. Use the key shown on the Jira issue in branch names, commit messages, and pull request titles. For an issue named
SHOP-284, examples include feature/SHOP-284-cart-validation and SHOP-284 Add tax validation.
- Verify an issue link. Open the Jira issue and look for its development information, such as a linked branch or pull request. If nothing appears, check the repository selection, issue key spelling, and app permissions before changing your team’s workflow.
Here’s why: installing the app creates the connection, but consistent issue keys make the connection useful. A team that uses SHOP-284 consistently can trace related code activity more easily than a team whose branches use vague names like quick-fix.
What the Jira–GitHub connection does
The integration connects development activity in selected GitHub repositories with Jira issues. When a developer uses a recognized Jira issue key in a branch, commit, or pull request, Jira can associate that activity with the matching issue.
That gives a project team a shared view of progress without asking every developer to write a separate status update. For example, a project manager can check whether work on SHOP-284 has a branch or pull request attached.
Issue keys create the relationship
A Jira issue key combines a project abbreviation and issue number, such as SHOP-284. The key acts as a recognizable reference when it appears in supported GitHub activity.
Let me explain: the key must match the issue exactly. A typo such as SHOP-248 may point to another issue or fail to create the intended relationship.
Repository access determines what Jira can see
Jira can only display activity for repositories the GitHub app is authorized to access. If a team connects one repository but commits code in another, the expected activity may not show on the issue.
For instance, an issue may be tracked in Jira while the work happens in a separate service repository. Check that both repositories are included if both need to appear in Jira.
Prepare your team’s Jira and GitHub workflow
Before connecting a large organization, decide which repositories belong with which Jira projects. A short inventory prevents a team from connecting everything by default and then sorting through unrelated activity.
You might be wondering: how much planning does this need? Usually, a simple mapping is enough. For example, connect the mobile app repository to the mobile Jira project and the payments service repository to the payments project.
Agree on a consistent issue-key format
Choose where the issue key should appear in branch names, commit messages, and pull request titles. Keep the format easy to scan, such as feature/SHOP-284-cart-validation for a branch and SHOP-284 Validate cart totals for a pull request.
A shared convention matters most when several developers contribute to one issue. If one person uses the key and another omits it, Jira may show only part of the development activity.
Decide who manages permissions
Identify the Jira administrators and GitHub organization owners who will approve and maintain the connection. Record which repositories are included and who can request changes to that selection.
This simple ownership plan helps when someone changes teams or a new repository is created. Without it, an integration can quietly lose access or keep access to repositories that no longer need to be connected.
Use linked development activity in everyday work
Once Jira displays GitHub activity, teams can use it to support planning and review. A developer can open a Jira issue, check its linked branch, and follow the related pull request without searching through several unrelated repositories.
The best part? The issue key can connect work at multiple stages. A team might use it in the branch name, preserve it in commit messages, and include it in the pull request title.
Example: track a small feature
Suppose the issue is SHOP-284, “Validate regional tax at checkout.” A developer creates feature/SHOP-284-regional-tax, commits with SHOP-284 Add regional tax validation, and opens SHOP-284 Validate checkout tax.
That consistent reference makes it easier to find the related development activity from the Jira issue. A reviewer can also use the issue description to understand the work’s goal before reviewing the code.
Keep Jira status updates intentional
Linked code activity can improve visibility, but it does not replace clear issue ownership or agreed status rules. A branch appearing on an issue does not necessarily mean the work is complete or ready for release.
For example, a team can keep “In progress” as the issue status until the pull request passes review. Agree on what each status means, then use GitHub activity as supporting context rather than a substitute for the team’s process.
Troubleshoot a missing Jira–GitHub link
If an issue does not show GitHub activity, check the simplest causes first: the issue key, repository access, and authorization status. A quick, methodical check is often more useful than reinstalling the app immediately.
But here’s the truth: a connection can be active while an individual branch or pull request remains unlinked. The integration needs the right repository access and a recognizable issue reference to associate activity with an issue.
Check the issue key and repository
Compare the key in GitHub with the key shown in Jira. Confirm that the activity is in a repository connected to the Jira site, especially if your organization has many repositories or multiple Jira projects.
If a developer created a branch without the issue key, update the branch or use another supported development activity that contains the correct key. Then check the Jira issue again.
Review app authorization and organization approval
Ask the GitHub organization owner to confirm that the app is approved and still has access to the selected repositories. Organization policies or a later permission change can affect the integration.
Also check the app’s status in Jira. A pending approval, revoked authorization, or missing repository selection can prevent activity from appearing even when the Jira issue itself is valid.
Confirm that the issue belongs to the connected Jira site
Teams sometimes have more than one Jira site or project key with similar names. Verify that the issue belongs to the Jira site connected to GitHub and that the key refers to the intended issue.
If the issue is still missing activity after these checks, ask your Jira administrator to review the app configuration and consult Atlassian’s current troubleshooting guidance. Avoid expanding repository access until you know what is missing.
ONES.com as a project management alternative
ONES.com brings project management and knowledge management together in one platform, with ONES Project for project management and ONES Wiki for knowledge management. ONES Project is a Jira alternative for teams evaluating how they manage issues, workflows, and project visibility.
If your main requirement is a direct Jira–GitHub connection, confirm that any platform you consider supports your specific GitHub workflow before changing systems. The capabilities below describe ONES Project’s project management features; they do not claim a GitHub integration.
Core capabilities
- Fragmented project tracking: ONES Project provides a central place to manage project work, helping teams keep issue tracking organized.
- Jira workflow familiarity: Jira-compatible workflows can make it easier for teams to preserve familiar process patterns while evaluating an alternative.
- Workflows that differ by team: Custom workflows let teams shape work stages around their own review and delivery practices.
- Fields that miss important context: Custom fields give teams a way to capture project-specific details alongside their work items.
- Sprint planning needs: Sprint management supports teams that plan and review work in iterative cycles.
- Manual, repetitive steps: Automation can reduce routine work when teams configure rules for recurring process actions.
- Limited progress visibility: Built-in reporting helps teams review project progress without relying solely on verbal updates.
- Too many separate add-ons: Native feature parity across cloud and self-hosted versions can reduce dependence on plugins for core project management needs.
Application scenarios
A software team reviewing its project management setup can compare its required Jira workflows, fields, sprint practices, and reports with ONES Project. It should separately validate any GitHub-specific requirements before making a migration decision.
An organization with deployment restrictions can evaluate ONES.com’s Cloud, On-Premise, Private Cloud, and Air-gapped deployment options. Teams can also explore the free plan for up to 30 seats when assessing whether the platform fits their project management needs.
ONES.com sells ONES Project and ONES Wiki separately. That gives a team evaluating project tracking a way to focus on ONES Project, while teams that also need knowledge management can assess ONES Wiki independently.
Common challenges and practical fixes
Challenge: the app requests access to too many repositories
Fix: Select only the repositories needed for Jira issue tracking, where GitHub’s authorization options allow it. Review the selection with the organization owner and revisit it when the team’s repositories change.
Challenge: development activity appears on the wrong issue
Fix: Check for a mistyped issue key or a copied key from another task. Make the correct key part of your branch and pull request conventions, and ask contributors to verify it before opening a pull request.
Challenge: the team expects GitHub activity to change Jira status automatically
Fix: Agree on which events, if any, should affect issue status, and configure workflow automation separately where appropriate. Keep review and completion criteria clear so a linked branch is not mistaken for finished work.
Challenge: the integration stops showing activity after permissions change
Fix: Ask a GitHub organization owner to review app authorization and repository access. Have a Jira administrator check the connection status, then test with one issue in a confirmed repository.
Frequently asked questions
Can I connect Jira to GitHub without adding issue keys?
Issue keys are the clearest way to associate branches, commits, and pull requests with Jira issues. Without a recognizable key, Jira may not be able to show the development activity on the intended issue. Ask your team to include the key in its GitHub naming conventions, then test the format with a real issue before rolling it out broadly.
Does the Jira–GitHub connection work with every repository?
It can display activity only for repositories the GitHub app is authorized to access. During setup, select the repositories your team needs, and confirm that the work is happening in one of them. If an issue has no linked activity, check repository access before assuming the Jira issue or GitHub activity is unavailable.
What should I do if a pull request does not appear on a Jira issue?
First, confirm the pull request title or related development activity includes the correct Jira issue key. Next, check that its repository is connected to your Jira site and that the GitHub app still has permission to access it. If those details are correct, ask your administrators to review authorization and app settings.
Can Jira automatically move an issue when a pull request is merged?
Do not assume that linking GitHub activity automatically changes an issue’s status. Issue transitions depend on your Jira workflow and any automation rules your team has configured. Decide which event should trigger a transition, such as a completed review, and test the rule with a non-critical issue before relying on it.
Does this setup guide apply to Jira Data Center?
This guide describes Jira Cloud and Atlassian’s GitHub for Jira app. Jira Data Center may use a different integration and administration process, so check the current Atlassian guidance for your specific Jira edition. Confirm compatibility, permissions, and setup requirements with your administrator before following Cloud instructions in a self-hosted environment.
Conclusion
Connecting Jira and GitHub gives your team a clearer view of code activity alongside project work. Install and authorize the app, select the right repositories, and use consistent Jira issue keys in branches, commits, and pull requests.
When links are missing, check the key, repository access, and authorization before making larger changes. A little care during setup can reduce status-chasing and help your team see how development work relates to the issues it is meant to solve.