Before you can link GitHub workflows and deployments to Jira, you’ll need to:
Connect GitHub Cloud to your Jira Software site using the GitHub for Jira app
Reference Jira issue keys in GitHub branches, commits, and pull requests
When GitHub is connected to your Jira Software site using the GitHub for Jira app, workflows and deployments from GitHub Actions can be linked to issues in your Jira Software project. If you’re new to GitHub Actions, you can get started by reading the GitHub Actions documentation set.
Use issue keys to link deployments to Jira issues
To link GitHub deployments to Jira, you must include Jira issue keys in commit messages, branch names, and pull requests.
Find the issue key for the Jira issue you want to link to, for example “DEV-2095”.
Check out a new branch in your repo, using the issue key in the branch name. For example, git checkout -b DEV-2095-<branch-name>.
When committing changes to your branch, use the issue key in your commit message. For example, git commit -m "DEV-2095 <summary of commit>".
When you create a pull request, use the issue key in the pull request title.
Once a deployment has run on a linked branch, commit, or pull request, you’ll see deployment information in your Jira issues, on the board, and on the deployments timeline.
View GitHub builds in Jira Software
GitHub workflows are displayed as “builds” in Jira. They’re shown on the development panel in Jira issues, on issue cards on your Jira board, and in the Releases hub.
You must have the project permission “View Development Tools” to see the Development panel in Jira issues. How to update project permissions
A build will be automatically linked to a Jira issue if the issue key is found in any commit messages related to the pull request. If you merge a branch without a pull request, only the last commit message of that branch will be checked for Jira issue keys.
Using the above illustration as an example, let’s assume you have two feature branches off the main branch. You’ve configured GitHub Actions 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 link specific workflow runs to their related Jira issues. For instance:
Workflow run #6 will be associated with Jira issues JIRA-1 and JIRA-2
Workflow run #7 will be associated with 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 part of the same pull request
To enable your GitHub workflows to run on pull requests, you must specify the branch name pattern of your pull request source branches in your workflow config like this:
12345on: pull_request: branches: - main - feature**
View GitHub deployments in Jira Software
Deployments from GitHub are shown on the development panel in Jira issues, on issue cards on your Jira board, in the Releases hub, and in the deployments timeline on the Deployments page. To add deployments to your GitHub Actions workflow, you must create a deployment action in GitHub using the action chrnorm/deployment-action@releases/v1.
The GitHub for Jira app only listens to deployment_status events. This means GitHub deployments will only be shown in Jira if they meet the following conditions:
Deployments are created using GitHub’s create deployment API or the chrnorm/deployment-action@releases/v1 action.
After creating a deployment, you must call the create deployment status API or the chrnorm/deployment-status@releases/v1 action at least once to update the status of the deployment.
The GitHub for Jira app identifies new GitHub deployments by scanning deployed branches for new commit messages that contain Jira issue keys.
Using the above illustration as an example, let's assume you have two feature branches off the main branch and you’ve 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'll see relevant deployments in the corresponding Jira issues. For instance:
Failed deployment #6 will appear in Jira issues JIRA-1 and JIRA-2
Deployment #7 will be visible in all related Jira issues (because none of the commits have been successfully deployed yet)
Map your deployment environments
Deployment events include the name of the environment your app was deployed to. To show environment details in your Jira issues, Jira needs to know whether the environment is a development, testing, staging, or production environment. Jira tries to guess which environment to map your deployment event to based on the environment name. For example, a deployment to an environment named prod would be considered a production environment.
If you use other environment names (for example, non-English environment names), Jira will show these as undefined environments. To resolve this, you can specify your custom environments by adding a file called .jira/config.yml to the main branch of your repository and mapping your custom environment names to the standard ones recognized by Jira.
Here’s an example:
123456789101112131415161718192021deployments: environmentMapping: development: - "dev*" - "Entwicklung" - "desenvolvimento" - "дев" testing: - "testes" - "Test" - "TST-*" - "тест" staging: - "Pre-Prod" - "STG-*" - "staging" production: - "Produktion" - "produção" - "продакшн" - "PROD-*"
Using the above example, a deployment event to an environment named "TST-3" would show up as a deployment to a testing environment in Jira, while a deployment to an environment named "produção" would show up as a production environment in Jira.
You can specify up to 10 glob patterns for each of the four valid environments in Jira. Once you add this configuration file, Jira will not be able to automatically detect environment names, so you will need to specify patterns for all your environment names.
