Discover Jira Cloud products
Learn more about Jira Cloud products, features, plans, and migration.
Use the GitHub for Jira app
By the end of this document, you'll be able to link your development information from GitHub to Jira effortlessly, gain insights from GitHub Actions directly in your Jira issues, and expertly map your deployment environments for more effective management.
View GitHub information in Jira issues
To view your GitHub development data in Jira, simply add a Jira issue key to your commit message, branch name, or PR title. For instance, including [DEV-2095] in any of these places will link data to the Jira issue with the key DEV-2095. Learn more about referencing issue keys.
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:
1
2
git commit -m "PROJ-123 add a README file to the project."
git push origin <branchname>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.
Learn more about integrating with development tools
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.
View Jira issues in GitHub
To view your Jira issues in GitHub, include a valid Jira issue key surrounded by brackets in a comment, like [DEV-2095]. It will automatically turn into a link to the Jira issue. Note that the brackets are needed for this to work.
GitHub Actions integration
GitHub Actions workflows and deployments are auto-synced with your Jira instance. If you're new to this, check out the GitHub Actions Documentation. To view CI/CD data from GitHub in Jira, include the Jira issue key in your commit message, branch name, or PR title. To learn more, check out our guides for builds and deployments.
View GitHub builds in Jira
GitHub for Jira automatically processes "workflow runs" from any GitHub Action workflows defined in your GitHub repositories and displays them in the "Builds" tab of an issue’s development information section.
Associating workflow runs with Jira issues
To associate a workflow run with a Jira issue, the app looks for Jira issue keys in all commit messages related to a pull request. This allows for a streamlined view of your builds directly from your Jira platform.
Here's an example to illustrate:
Let’s assume you have two feature branches off the main branch and have GitHub Actions configured so that every commit on both the feature branches (green dots) and the main branch (blue dots) triggers a workflow to build and test your codebase.
By including Jira issue keys (JIRA-*) in your commit messages, you can view specific workflow runs within the related Jira issues. For instance, Workflow run #6 will be visible in Jira issues JIRA-1 and JIRA-2, while Workflow run #7 will appear in Jira issues JIRA-1, JIRA-10, and JIRA-11. Workflow run #2 will be associated with the Jira issue JIRA-1 only. Workflow run #4 will be associated with both JIRA-1 and JIRA-2, because they're both part of the same pull request.
Note: The app specifically looks for Jira issue keys in commits that are part of a pull request. If you merge a branch without a pull request, the app will only search for Jira issue keys in the last commit message of that branch.
To enable your GitHub workflows to run on pull requests, make sure to include the branch name pattern of your pull request source branches in your GitHub workflow config like this:
1
2
3
4
5
on:
pull_request:
branches:
- main
- feature**ViewGitHub deployments in Jira
GitHub for Jira allows you to see your GitHub deployments right in Jira. These deployments are made visible in Jira issues whenever they're created using GitHub's deployment API.
Associating deployments with Jira issues
Deployments are linked to Jira issues by scanning for Jira issue keys in all commit messages on the deployed branch since the last successful deployment.
Here's an example to illustrate:
Let's assume you have two feature branches off the main branch and have set up GitHub Actions so that each push on the main branch triggers a deployment.
If you include Jira issue keys (JIRA-*) in your commit messages, you will see relevant deployments in the corresponding Jira issues. For instance, failed deployment #6 will appear in Jira issues JIRA-1 and JIRA-2, and deployment #7 will be visible in all related Jira issues (because none of the commits have been successfully deployed yet).
To create deployments as part of your GitHub Actions workflow, you can utilize a deployment action. Use the action chrnorm/deployment-action@releases/v1 to create a deployment and remember to update the state of a deployment useing the chrnorm/deployment-status@releases/v1.
Bear in mind that the GitHub for Jira app only listens to deployment_status events. Merely creating a deployment using the create deployment API or the chrnorm/deployment-action@releases/v1 action won't suffice. After creating a deployment you need to call the create deployment status API (r the chrnorm/deployment-status@releases/v1 action) at least once to update the status of that deployment (whether it's success, failure, pending, etc.).
Environment mapping
Every deployment event includes the name of the environment to which your app is deployed. To optimize your issue and deployment views, Jira needs to know if the environment is development, testing, staging, or production.
In response, GitHub's integration tries to guess the environment type from the environment name. For instance, if it includes the word “prod”, it's taken as a production environment. If “test” is found, it's considered a testing environment, and so on.
If you use custom or non-English names for your environments, the correct environment type may not be identified, resulting in an "undefined environment" message in Jira. To resolve this, you can add a .jira/config.yml file to the main branch of your repository to map your custom environment names to the standard ones recognized by Jira.
Here’s an example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
deployments:
environmentMapping:
development:
- "dev*"
- "Entwicklung"
- "desenvolvimento"
- "дев"
testing:
- "testes"
- "Test"
- "TST-*"
- "тест"
staging:
- "Pre-Prod"
- "STG-*"
- "staging"
production:
- "Produktion"
- "produção"
- "продакшн"
- "PROD-*"In this setup, you can specify up to 10 glob patterns for each of the four valid environment types in Jira. For instance, if the environment name from your deployment event is "TST-3", it would be identified as a deployment to a testing environment in Jira. If the environment name is "produção", it would be considered a production environment in Jira.
Note: Once you add this configuration file, automatic detection will no longer work. You'll need to specify patterns for all of your environment names.
Automation
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?