• Products
  • Documentation
  • Resources

Reference issues in your development work

Enjoy the seamless integration of issues and code when your admin has connected Jira Software to Bitbucket Cloud, GitHub, or other supported developer tools.

Before you begin

To reference Jira issues while committing, building, and deploying code with Bitbucket, GitHub, or other supported developer tools:

  1. Find the issue key for the Jira issue you want to link to, for example “JRA-123”. You can find the key in several places in Jira Software:
    • On the board, issue keys appear at the bottom of a card.
    • On the issue’s details, issue keys appear in the breadcrumb navigation at the top of the page.
    Learn more about issues and issue keys.

  2. Checkout a new branch in your repo, using the issue key at the beginning of the branch name. For example, git checkout -b JRA-123-<branch-name>.

  3. When committing changes to your branch, use the issue key at the beginning of your commit message to link those commits to the development panel in your Jira issue. For example, git commit -m "JRA-123 <summary of commit>".

You need to push something to the connected repository for your tools to recognize and sync with Jira. Sometimes, it may take a few minutes for a complete sync to happen.

After you push your branch, you’ll see development information in your Jira issue.

To view linked development information in Jira Software:

  1. Navigate to the issue.

  2. Under Development, select the number of branches or the number of commits to see additional information.

Development actions that affect your issues

The following actions in your development environment will link and update your issues in Jira. More actions are available if your Jira admin has enabled smart commits. Learn more about using smart commits.

Branches

Include the issue key at the beginning of the branch name when you create the branch to link it to your Jira issue.

For example: git checkout -b JRA-123-<branch-name>

This works by default in connected Bitbucket, GitLab, GitHub, GitHub Enterprise, and Fisheye tools.

If you’re using Bitbucket Cloud, you can create a branch directly from your Jira issue. Under Development, select + > Create branch. If you create a branch this way, the issue key is automatically added to the name of the branch.

Builds

Build information works by default for connected Bamboo and Bitbucket Pipelines tools.

For 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.

For Bitbucket Pipelines, simply include the issue key in the branch name. Learn more about Bitbucket Pipelines.

Commits

Include the issue key at the beginning of the commit message to link the commit to your Jira issue.

For example: git commit -m "JRA-123 <commit message>"

This works by default in connected Bitbucket, GitLab, GitHub, GitHub Enterprise, and Fisheye tools.

Deployments

A deployment to an environment, such as production or testing, is linked 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.

This works by default in connected Bamboo and Bitbucket Pipelines tools.

Pull requests

Do at least one of the following:

  • Include a commit in the pull request that has the issue key in the commit message. Note, the commit cannot be a merge commit.

  • Include the issue key at the beginning of the pull request title.

  • Ensure that the source branch name also includes the issue key at the beginning of the branch name.

This works by default in connected Bitbucket, GitLab, GitHub, and GitHub Enterprise tools.

If you create the pull request from the development panel in a Jira issue, the issue key is added automatically.

Reviews

Include the issue key at the beginning of the review title when you create the review to link the review to your Jira issue.

For example, name your review "JRA-123 <review summary>" and start the review.

This works by default if you connect Jira to Crucible.

Last modified on Aug 9, 2021
Cached at 1:37 AM on Oct 16, 2021 |

Additional Help