Learn more about Jira Cloud products, features, plans, and migration.
Integrate Jira Cloud with Confluence, development tools, apps, and self-hosted tools using OAuth and feature flags.
Control who has access to your Jira Cloud products and give them the right permissions to perform their role.
Learn how to set up, customize, and manage Jira Cloud projects.
Explore issues, issue types, issue custom fields, issue screens, custom field context, and issue field configurations in Jira Cloud.
Define the lifecycle of your work and learn about issue workflow schemes and the issue collector.
Learn more on how you can set up Jira Cloud for your team.
When your GitHub or GitHub Enterprise account is linked to Jira Software, your team gets to see their branches, commit messages, pull requests, builds and deployments right in the context of the Jira Software issues they're working on. Learn more about integrating with development tools.
Connect a GitHub Cloud or GitHub Enterprise Cloud account to Jira Software
You can integrate Jira Cloud with GitHub Cloud or GitHub Enterprise Cloud using the Marketplace app. Linking between these accounts gives you quick, direct access to branches, commits, pull requests, builds and deployments while viewing Jira Software tickets in planning and during standups.
To connect a GitHub Cloud Organization with Jira Software:
Install the (free) GitHub for Jira app from the Atlassian Marketplace and follow the instructions to complete the installation.
Select Get started to go to the GitHub configuration page (or go to Apps > Manage apps and select Configure integration in the GitHub menu).
Select Connect GitHub organization.
Find the GitHub organization you want to integrate with and select Connect, or select Install GitHub for Jira on a new organization to install the GitHub for Jira app on another GitHub organization.
Back on your GitHub configuration page, select Connect GitHub organization again and click Connect next to the organization you want to connect to your Jira site.
Once your organization is successfully connected, you’ll see it on the GitHub configuration page in Jira:
You can see development information about the branches, commits, pull requests, builds, and deployments that reference Jira issues on your site. Learn more about referencing issues in your development work.
Connect a GitHub Enterprise Server account to Jira Software
These instructions are for GitHub Enterprise Server, meaning the on-premise version of GitHub where you manage the installation on your own infrastructure. If you have GitHub Cloud or GitHub Enterprise Cloud, follow the instructions above rather than using the DVCS Connector.
To connect your GitHub Enterprise Server account to Jira Software, you must use the DVCS Connector provided in Jira. You'll need admin permissions on both Jira Software and the GitHub Enterprise account you want to link.
To integrate correctly, the DVCS Connector must be able to call your GitHub Enterprise Server. Please speak to your network admin to make sure the GitHub Enterprise Server is available to be called from Atlassian’s IP addresses. Doing this requires opening a hole in your firewall, which might not be acceptable to some security teams. Reverse proxies are currently not supported by DVCS. We’re working on an alternative solution to connect GitHub Enterprise Server accounts to Jira Software while running behind the firewall. Learn more about IP addresses for Atlassian cloud products.
GitHub Enterprise Server doesn’t support the authorization of Personal Access Codes through SSO. This means that even if your network admin allows traffic from Atlassian IP addresses, DVCS will fail to connect to your GitHub Enterprise Server installation. This limitation will remain until the GitHub Enterprise Server team introduces the same mechanic they provide for GitHub Enterprise Cloud.
Step 1. Create an OAuth access token for your GitHub Enterprise account
The DVCS Connector requires an OAuth access token, which you create in your GitHub Enterprise account. You should create the access token in the GitHub Enterprise account that owns the repositories you want to link. If you are linking repositories for a team, you should generate this token using the team account.
Create the OAuth token as follows:
Log in to GitHub Enterprise as a user with admin permissions on the account.
Navigate to Settings > Developer settings > OAuth apps
Choose New OAuth App.
Enter a name for Application Name.
Enter the Jira Software URL for both the URL and Callback URL fields. Use lower case. Press Register Application.
Make sure you enter the Jira Software Base URL (for example, https://myjiracloud.atlassian.net/) for both the Homepage URL and Authorization callback URL fields. Don't use the dashboard URL, such as https://myjiracloud.atlassian.net/secure/Dashboard.jspa.
Keep your browser open in your GitHub Enterprise account while you go on with step 2.
Step 2. Add the OAuth token in Jira Software
After you create a key and secret in GitHub Enterprise, you go back to Jira Software and enter the account, the OAuth key, and secret as follows:
Log in to Jira Software as a user with admin permissions.
Choose > Products.
From the Integrations section on the left, choose DVCS accounts.
Click Link GitHub Enterprise account.
Enter your GitHub User Account name.
Enter your GitHub Enterprise site URL as the Host URL.
Copy the Client ID and Client Secret values from your GitHub Enterprise site into the dialog.
Leave the default auto link and Smart Commits (recommended) as is or change them:
9. Click Add. If you get redirected to a blank page at this point, see DVCS connection to GitHub produces blank page.
10. Grant access when prompted.
11. When Jira connects successfully, you'll see your account on the 'DVCS accounts' page.
The account you just connected and all of its repositories appear on the 'Managed DVCS Accounts' page. The initial synchronization starts automatically. After that, the system continues to sync your repository automatically on a regular basis.
Reset the OAuth access token for your GitHub Enterprise account
Regenerate the OAuth token as follows:
Log in to GitHub Enterprise as a user with admin permissions on the account.
Navigate to Settings > Developer settings > OAuth apps.
Select your OAuth app.
On your app page, click Revoke all user tokens to remove all old user tokens for this application.
Click Generate a new client secret.
Copy the new client secret and then delete the old client secret.
Go to the DVCS accounts page in Jira.
Click the More options (•••) menu next to your existing GitHub Enterprise account or workspace.
Select Reset OAuth settings.
Paste the existing Client ID as Key and the new client secret as Secret to regenerate the access token.
The connector does not automatically trust the key and secret. It asks you to authorize the DVCS connection using an account and password combination. The authorizing account need not be the account you used to create the key and secret, but it should have administrative access on all the repositories you want to link.
When you link an account using the Jira DVCS Connector, the connector adds a post-commit webhook to all the repositories owned by the account in GitHub Enterprise. When a commit happens, the DVCS Connector collects the commit message for processing.
On the Jira Software side, the repositories owned by your GitHub Enterprise account appear on the 'DVCS accounts' page. A team member may create repositories under their individual GitHub Enterprise account, but assign the team as the owner. These repositories also appear in the list.
Automatic synchronization and temporarily disabling a link
After you link an account, Jira Software automatically starts looking for commits that reference issue keys. The summary shows the synchronization results and errors if any. A synchronization of commit data from the GitHub Enterprise repository to Jira Software can take some time. As the synchronization progresses, the commits appear in related issues. You can always enable and disable the linking of repositories with Jira Software as needed.
Example of how commit information appears in a Jira Software project
When a developer makes a commit, they should add a Jira Software issue key to the commit message, like this:
Jira Software uses the issue key to associate the commit with an issue, so the commit can be summarized in the Development panel of the Jira Software issue.
Project users must have the 'View Development Tools' permission to see commit information in the Development panel in a Jira Software issue. A Jira Software admin can edit a project's permission schema to grant this permission. Learn more about managing project permissions.
Use repo activity to automatically update issues in company-managed projects
In company-managed software projects, you can automate your issue’s workflows to transition issues when activity happens in your GitHub repos.
We recommend you do this using automation for Jira. To automate your workflow:
Navigate to your company-managed project.
Select Project settings > Automation.
Select the Library tab.
Under DevOps, select any of the pre-configured rules.
When previewing the rule’s configuration, select Turn it on to enable it.
Your project’s automation library comes with 3 pre-configured rules that transition issues along your workflow as development happens in your connected source code tool:
When a branch is created → then move issue to in progress
When a commit is made → then move issue to in progress
When a pull request is merged → then move issue to done
You can use source code triggers to automate other parts of your Jira projects. Learn more about automation for Jira.
Was this helpful?