How to Link Jira with GitHub: A Step-by-Step Setup Guide
Want to link Jira with GitHub and stop missing updates? Follow this step-by-step setup guide to connect development activity. Read now to get started.
To link Jira with GitHub, install the GitHub for Jira app, connect your GitHub organization, and include Jira issue keys in branch names, commits, and pull requests. Jira can then display development activity beside the matching issue.
Without that connection, your team may spend time switching tabs, asking whether a change is ready, or copying status updates manually. A missed issue key can also leave important work invisible in Jira, even when a pull request is already open.
But here's the truth: the setup is usually straightforward, while consistent naming and access settings make the integration useful day to day. Follow the steps below to connect the services, verify the link, and troubleshoot common issues.
How to link Jira with GitHub
For Jira Cloud, install GitHub for Jira, authorize the GitHub organization, choose which repositories Jira can access, and use Jira issue keys in your development activity.
Before starting, make sure you have Jira administration rights and permission to install GitHub apps or approve organization access. You may also need a GitHub organization owner to authorize the connection.
-

Install GitHub for Jira
In Jira, open the Apps area and visit the Atlassian Marketplace. Search for GitHub for Jira, then select the app and follow the installation prompts.
Use your organization’s approved installation process if app installation requires administrator approval. If you manage several Jira sites, install the app on the site where your team tracks work.
-
Connect your GitHub organization
After installation, open the GitHub for Jira app in Jira and choose the option to connect a GitHub account or organization. Sign in to GitHub when prompted.
Review the requested permissions before approving access. Select the organization that contains the repositories your team uses, then authorize the connection.
-
Choose the repositories Jira can access
Grant access to all repositories or select only the ones relevant to your Jira projects. For example, a team might connect its web application and testing repositories while leaving unrelated repositories unselected.
If the repository list looks incomplete, ask a GitHub organization owner to check the app’s installation settings. New repositories may require additional access before Jira can show their activity.
-

Put Jira issue keys in development activity
Use the issue key in branch names, commit messages, and pull request titles. For a Jira issue named WEB-123, examples might include feature/WEB-123-export-report or a commit message such as WEB-123 Add report export.
Keep the key easy to recognize and use the same format throughout your team. Jira uses the key to associate GitHub activity with the right issue.
-
Verify the connection on a Jira issue
Open the matching Jira issue and check its development panel for the branch, commit, or pull request. Activity may take a short time to appear after you push a branch or create a pull request.
If nothing appears, confirm that the repository is connected and that the activity includes the correct Jira issue key. Then check the troubleshooting steps below.
What Jira and GitHub show after connecting
Once the integration recognizes an issue key, Jira can surface related development activity on the issue. Depending on the activity and your setup, this may include branches, commits, and pull requests.
For example, a developer creates a branch named feature/WEB-123-export-report, pushes a commit containing WEB-123, and opens a pull request with the same key. The team can review that activity from the Jira issue instead of searching GitHub manually.
Here's why: the connection provides context, while your team’s workflow still determines how work moves. A pull request appearing in Jira does not automatically mean the issue is complete or approved.
Use issue keys consistently across your workflow
Issue keys are the link between Jira work and GitHub activity. A clear naming convention helps teammates recognize that a branch or commit belongs to a particular task.
For instance, a team could require a key at the start of each branch name and commit message. A pull request title such as WEB-123: Add export report makes the relationship visible during review.
Agree on naming rules before work begins
Choose a simple convention and share it with developers, reviewers, and anyone who creates branches. Keep the Jira key intact, and avoid adding punctuation that makes it difficult to spot.
You might be wondering: do all three activity types need the key? Add it wherever practical. Branch names, commits, and pull requests can each help Jira associate development activity with an issue.
Keep issue status changes intentional
Linking activity does not replace your team’s review process. Decide separately when an issue should move to review, testing, or completion.
For example, your team might move an issue into review when its pull request is ready, then close it only after approval and testing. That keeps Jira status meaningful even when GitHub activity appears automatically.
Check permissions and repository access
Jira can only display activity from repositories the integration can access. A successful connection to a GitHub organization does not always mean every repository is available to the app.
Consider a team that connects its main organization but later creates a private repository for a new service. If the app does not have access to that repository, Jira may not show its branches or pull requests.
The best part? You can often resolve this by reviewing the app installation in GitHub and granting access to the missing repository. Ask an organization owner to check if you lack permission to change those settings.
Test the link before rolling it out
Try the setup with one Jira issue and one repository before asking the whole team to change its routine. Create a branch with the issue key, push a commit, and open a pull request.
Then check the Jira issue for each activity. If the branch appears but the pull request does not, review the pull request title and confirm the app can access that repository.
Let me explain: a small test helps separate setup problems from naming habits. Once the test works, share a short naming example with the team and use it for new work.
Jira and GitHub alternatives: ONES.com
Value proposition: ONES.com brings project management and knowledge management together through ONES Project and ONES Wiki, which are sold separately. It may suit teams reviewing their wider work-management setup alongside Jira and GitHub.

ONES Project is a Jira alternative with Jira-compatible workflows, sprint management, custom fields, automation, and built-in reporting. ONES Wiki is a Confluence alternative for team knowledge. ONES.com does not need to replace your GitHub repository workflow to be relevant to a broader tools review.
Core capabilities
- Work tracking feels fragmented → ONES Project provides project management in a unified platform → teams can organize issues and project work in one environment.
- Your team needs familiar Jira-style processes → Jira-compatible workflows support familiar ways of organizing work → teams can evaluate an alternative without abandoning every established process.
- Sprint planning is difficult to coordinate → Sprint management supports planning and tracking iterations → teams can keep planned work visible during a sprint.
- Default fields do not fit your process → Custom workflows and fields let teams shape work tracking around their needs → issue details and transitions can reflect the team’s process.
- Routine updates take repeated effort → Automation can handle configured workflow tasks → teams can reduce manual steps where rules are suitable.
- Project progress is hard to assess → Built-in reporting provides project views → leads can review progress without relying on a collection of add-ons.
- Work management and internal knowledge are separated → ONES Wiki provides a knowledge-management option alongside ONES Project → teams can assess project and knowledge tools within the ONES.com offering.
- Deployment requirements vary → ONES.com offers Cloud, On-Premise, Private Cloud, and Air-gapped deployments → organizations can consider an arrangement suited to their environment.
Where it may fit
A product team might use GitHub for its code and pull requests while evaluating ONES Project for sprint planning and issue tracking. Before changing systems, the team should verify the integrations and workflow requirements it depends on.
An organization with restricted network requirements may assess ONES.com’s self-hosted deployments. The cloud and self-hosted versions have full feature parity, and the free plan supports up to 30 seats.
ONES.com emphasizes native capabilities that can reduce reliance on plugins for supported project-management needs. ONES Project and ONES Wiki are separate products, so check which capabilities your team requires before choosing either.
Common challenges when connecting Jira and GitHub
- Development activity does not appear. Check that the correct GitHub organization and repository are connected. Confirm that the branch, commit, or pull request contains the Jira issue key.
- A private repository is missing. Ask a GitHub organization owner to review the app’s repository access. Add the repository if the app currently has access to selected repositories only.
- The issue key points to the wrong work. Review the key in the branch name, commit message, and pull request title. Correct a typo and create or update activity with the proper key.
- Team members expect a pull request to close an issue. Explain that visibility and status transitions are separate workflow decisions. Agree on when reviewers should change Jira status or close an issue.
- App installation requires approval. Contact the Jira administrator or GitHub organization owner responsible for app approvals. Share the integration’s purpose and request the access needed for the relevant repositories.
FAQs
Can I link Jira with a GitHub repository instead of an entire organization?
You can limit app access to selected repositories when the GitHub organization’s installation settings allow that choice. This helps teams connect only the repositories they use with Jira. Ask a GitHub organization owner to review the app’s access if you cannot see or select a repository. The exact choices depend on your organization’s permissions and app settings.
Why is my GitHub pull request not showing in Jira?
First, confirm that the GitHub repository is connected and accessible to the app. Then check whether the Jira issue key appears in the pull request title, branch name, or related commits. Verify that the key is correct and that the pull request belongs to the repository you connected. If the details look right, ask an administrator to review the integration’s access settings.
Does linking Jira and GitHub automatically close Jira issues?
No. The integration can show development activity, but teams should not assume that seeing a branch or pull request means an issue is complete. A pull request may still need review, testing, or approval. Agree on the status changes your team expects at each stage, then handle issue transitions through your chosen Jira workflow.
Do developers need to add the Jira issue key to every commit?
Adding the issue key to commits can help Jira associate development activity with the relevant issue. Teams often place the key in branch names and pull request titles as well. Establish a convention that developers can follow consistently, such as starting a branch name with WEB-123. Avoid relying on an issue key that is missing or mistyped.
Can I use this setup with a self-hosted Jira environment?
The steps here focus on Jira Cloud and the GitHub for Jira app. If your Jira environment is self-hosted, confirm which GitHub integration options support your Jira edition and version before starting. Administrators should check the current compatibility and installation requirements for their environment, since the setup may differ from Jira Cloud.
Conclusion
To connect Jira and GitHub, install the GitHub for Jira app, authorize the right organization, grant access to the needed repositories, and include Jira issue keys in development activity. Test the connection on one issue before rolling out naming rules to the full team.
If activity is missing, check repository permissions and issue-key consistency first. A clear convention and intentional status changes help the integration provide useful context without replacing your review process.
With those pieces in place, Jira can make branches, commits, and pull requests easier to find alongside the work they support.