How to Connect GitHub to Jira: A Step-by-Step Guide in 2026
Want Jira to reflect your GitHub work? Learn how GitHub for Jira links branches, commits, and pull requests to issues. Read now to get started.
When GitHub activity and Jira issues live apart, developers can spend time explaining work instead of moving it forward. A pull request may be ready, but the Jira ticket still looks untouched. Then your team has to chase updates, reconstruct what happened, and wonder whether the right repository is connected.
That friction can make project tracking unreliable, especially when several teams use different naming habits or access settings. The good news is that you can connect GitHub to Jira and link branches, commits, and pull requests to Jira issues. Here’s how to set up the connection, use issue keys consistently, and check that activity appears where your team expects it.
How to Connect GitHub to Jira: Step-by-Step
For Jira Cloud and GitHub.com, the usual setup is to install the GitHub for Jira app, authorize access, and connect the repositories you want Jira to display. Then include a Jira issue key, such as PROJ-123, in branch names, commit messages, or pull request details.
Here’s the practical sequence:
Check access and prerequisites. Confirm you have permission to install apps in Jira and authorize an app in the relevant GitHub organization. Ask an administrator for help if you lack either permission.
Install GitHub for Jira. In Jira, open the app marketplace or the product’s app management area, find GitHub for Jira, and start installation. Review the requested permissions before approving.
Authorize the GitHub connection. Sign in to the correct GitHub account or organization when prompted. Approve the installation, then return to Jira to continue setup.
Select repositories. Choose the repositories your team wants to connect. If the repository is missing, check the GitHub app’s organization access and repository selection.
Add Jira issue keys to development work. Include a key such as PROJ-123 in a branch name, commit message, or pull request title. The key must match an existing Jira issue.
Verify the connection. Open the matching Jira issue and look for its development details. Confirm that the expected branch, commit, or pull request appears.
But here's the truth: installing the app is only half the job. Jira can’t reliably associate activity with an issue if your team omits the issue key or uses a key that doesn’t exist.
What to Check Before You Connect the Apps
A smooth setup starts with the right access. You’ll typically need Jira app installation privileges and permission to authorize the app for your GitHub organization. If security settings require administrator approval, arrange that before asking your team to test the connection.
Next, confirm which Jira and GitHub deployments your team uses. The exact setup can differ between Jira Cloud, Jira Data Center, GitHub.com, and GitHub Enterprise Server. Check the current app requirements for your deployment before following Cloud-specific steps.
Here’s why: a connection can appear incomplete when the app is authorized for one organization but your team’s repositories belong to another. For example, a developer might connect a personal GitHub account while the project repository sits inside a company organization.
Choose a small test repository and one open Jira issue. This gives you a low-risk way to check permissions, issue-key recognition, and development details before connecting repositories used by the whole team.
Connect Jira and GitHub in the Right Order
Install and authorize the app
Open Jira’s app management area and locate GitHub for Jira. Start the installation, review the requested access, and follow the prompts to authorize the correct GitHub account or organization.
Use an account with the appropriate administrative permissions. If GitHub requires an organization owner to approve the app, ask that person to complete the approval rather than repeatedly retrying with an account that lacks access.
Choose the repositories Jira should see
After authorization, select the repositories you want connected. Start with a focused set, such as the repositories owned by one product team, instead of connecting everything immediately.
Then check the repository access settings in GitHub. Some organizations require an administrator to grant an app access to individual repositories. A successful authorization doesn’t always mean every repository is included.
The best part? A small initial connection makes it easier to spot mistakes. If Jira shows development activity for your test issue, expand the setup in manageable groups.
Link Branches, Commits, and Pull Requests to Issues
Jira needs a recognizable issue key to associate development activity with the right work. A key usually combines a project code and issue number, such as PROJ-123. Copy the key from the Jira issue to avoid typos.
Use a consistent issue-key pattern
Branch: feature/PROJ-123-add-export
Commit: PROJ-123 Add export option
Pull request title: PROJ-123 Add export option
When a developer opens the Jira issue, its development area can show matching branches, commits, and pull requests. The exact information shown depends on the connection and the activity available in GitHub.
Let me explain one common misunderstanding: linking a pull request to an issue does not automatically mean the issue will move to another status. If you want status changes, review your Jira automation rules or supported smart commit behavior, then test the result carefully.
Test the Connection and Fix Common Setup Problems
Use one test issue and make a small change in the connected repository. Put the issue key in the branch name or commit message, push the work, and check the Jira issue for development details.
If nothing appears, check the likely causes in order. Verify that the issue key is correct, the repository is connected, and the GitHub app has access to that repository. Also confirm that the activity belongs to the account and project you’re checking.
You might be wondering: how long should you wait? Allow time for activity to appear, then refresh the issue and check the connection’s status. If the problem continues, review the app’s permissions and the current setup guidance for your specific Jira and GitHub deployments.
For example, a team may connect its main repository but miss a second repository used for pull requests. The issue key is valid, yet Jira shows no activity because the relevant repository was never authorized.
ONES.com as a Project Workflow Option
ONES.com brings project management and knowledge management together in one platform, powered by ONES Assistant. ONES Project is a Jira alternative for managing project work, while ONES Wiki provides knowledge management; the products are sold separately.
If you’re reviewing how your team manages issues alongside GitHub development, assess the project workflow separately from the code-hosting connection. Confirm the GitHub integration requirements for your chosen deployment before planning a migration or promising that a particular repository connection will work.
Core capabilities for project teams
Disconnected project processes: ONES Project supports custom workflows, helping teams shape issue stages around their actual review and delivery process.
Limited issue detail: Custom fields let teams capture information relevant to their work, so tickets can carry useful context beyond a short summary.
Manual sprint tracking: Sprint management gives teams a way to plan and monitor work within iteration-based project routines.
Repeated status updates: Automation can handle supported workflow actions, reducing routine manual steps when rules are configured appropriately.
Need for project visibility: Built-in reporting helps teams review project progress without relying solely on ad hoc status discussions.
Existing Jira habits: Jira-compatible workflows can make it easier for teams familiar with Jira-style project processes to evaluate ONES Project.
Plugin sprawl: Native capabilities may reduce reliance on multiple add-ons for common project workflows, depending on what your team needs.
Deployment constraints: ONES.com offers Cloud, On-Premise, Private Cloud, and Air-gapped deployments, giving organizations different hosting choices.
ONES.com offers a free plan for up to 30 seats. Its cloud and self-hosted versions have feature parity, which can help teams compare deployment options without assuming that self-hosting means giving up features.
Where this approach may fit
A team reviewing Jira alternatives: You can compare ONES Project’s workflows, reporting, sprint management, and deployment options against your current project requirements. Separately confirm whether your GitHub setup is supported before changing systems.
An organization with restricted hosting needs: A team evaluating On-Premise, Private Cloud, or Air-gapped deployment can assess ONES Project’s project-management capabilities alongside its security and operational requirements.
A team that needs project and knowledge management: ONES Project and ONES Wiki address different needs within the ONES.com platform. Since they are sold separately, evaluate each product against the work you need it to support.
Common Challenges and Practical Fixes
The app is installed, but repositories are missing
Problem: Jira shows a successful connection, but a team repository isn’t available. Fix: Check whether the GitHub organization approved the app and whether that repository was selected for access.
Development activity does not appear on the issue
Problem: A branch or pull request exists, but the Jira issue looks unchanged. Fix: Confirm the issue key is spelled correctly and appears in a supported field, such as the branch name or pull request title.
The issue key points to the wrong project
Problem: A typo or outdated project key can prevent Jira from finding the intended issue. Fix: Copy the key directly from Jira and check that the issue is still available to your team.
Issue status does not change when code is merged
Problem: A linked pull request is visible, but the Jira issue remains in its current status. Fix: Treat issue linking and status transitions as separate behaviors. Review your automation or smart commit configuration and test it with a non-critical issue.
FAQs About Connecting GitHub to Jira
Does linking GitHub to Jira automatically update an issue’s status?
No. A connection can display development activity on a Jira issue, but that does not necessarily change the issue’s workflow status. Status transitions depend on your configuration, such as Jira automation or supported smart commit actions. Test any transition rule with a low-risk issue first, and confirm that the resulting status matches your team’s process.
Where should I put the Jira issue key?
Put the key in a branch name, commit message, or pull request title so Jira can associate the development activity with the issue. For example, use PROJ-123 in feature/PROJ-123-add-export. Follow one shared naming convention, and copy the key from Jira to avoid incorrect project codes or issue numbers.
Why can’t Jira see a GitHub repository?
The app may not have access to the repository, even if the GitHub account or organization was authorized. Check the app’s repository selection and organization approval settings. Also confirm you connected the organization that owns the repository, rather than a personal account or a different company organization.
Can I connect every repository at once?
You may be able to grant access to multiple repositories, depending on your app permissions and organization settings. However, starting with a small group makes it easier to verify access and issue linking. Expand the connection after a test issue displays the expected branch, commit, or pull request details.
Will the setup work with every Jira and GitHub deployment?
Setup requirements can vary between Jira Cloud, Jira Data Center, GitHub.com, and GitHub Enterprise Server. Check the current app requirements for your specific deployment combination before starting. If the standard app does not fit your environment, ask your administrators to review the available integration options and security requirements.
Conclusion
Connecting GitHub to Jira usually means installing and authorizing the GitHub for Jira app, granting access to the right repositories, and using Jira issue keys consistently. Test with one issue before rolling the connection out across your team.
When activity still fails to appear, check repository permissions, organization approval, and the issue key first. Keep issue linking separate from status automation, and verify each behavior before relying on it in your delivery process.
That small setup can save your team from chasing routine development updates. If you’re also reconsidering project management workflows, compare your current Jira setup with alternatives such as ONES Project, while verifying GitHub requirements for your environment.