Referencing issues in your development work
If your administrator has connected Jira Software to your development tools, you can easily synchronize your development work with your issues — just reference an issue key(s) in your commits, branches, pull requests, etc, and you will enable the following:
- Show links to your development work on the issue in a Development panel
- Show details of the development work in the Development column on your list view of your search
- Automatically transition the issue to a new status, if your administrator has set up workflow triggers
- Collate your issues and development work on the Version details page, which is used to track and release the version
Note, when you reference your issue key(s), your connected development tools will also have links back to the relevant issues.
The table below describes how to reference an issue key in a commit, branch, pull request, or review. In all cases, the issue key must conform to the default Jira key format – that is, two or more uppercase letters ([A-Z][A-Z]+), followed by a hyphen and the issue number. For example, ABC-123.
Event | Dev Tool | Instructions |
|---|---|---|
| Create commit | Bitbucket, GitHub, GitHub Enterprise, Fisheye | Include the issue key in the commit message. For example, a commit message like this "TIS-1 Initial commit" will automatically transition the TIS-1 issue from 'To Do' to 'In Progress'. |
| Create branch | Bitbucket, GitHub, GitHub Enterprise, Fisheye | Include the issue key in the branch name when you create the branch. For example, if you name your branch "TIS-2 feature", it will automatically transition the TIS-2 issue from 'To Do' to 'In Progress'. |
| Create/Reopen/Decline Merge pull request | Bitbucket, GitHub, GitHub Enterprise | Do at least one of the following:
For example, if you create a pull request that has "TIS-3" in the title, it will automatically transition the "TIS-3" issue from 'In Progress' to 'In Review'. If you reopen, decline, or merge the pull request, it will also transition the "TIS-3" issue accordingly. |
| Start/Reject/Abandon/Close review | Crucible | Include the issue key in the review title when you create the review. For example, if you name your review "TIS-4 New story" and start the review, it will automatically transition the TIS-4 issue from 'In Progress' to 'In Review'. If you reject, abandon, or close the review, it will also transition the "TIS-4" issue accordingly. |
| Create build plan | Bamboo | A build is automatically linked to an issue if one of the build's commits includes the issue key in its commit message. The issue key must be included in the commit to activate this feature. |
| Create deployment project | Bamboo | A deployment to an environment, such as Production or testing, is linked to an issue if a commit associated with the deploy contains the issue key in its commit message. The issue key must be included in the commit to activate this feature. |