Git Integration for Jira Cloud Documentation

Linking git commits to Jira issues

To create a link between your Git commit and a Jira issue, developers must include the issue key in the commit comment.

On this page:

How commit linking works
Best practices for linking
Associating git commits manually to Jira issues
How to link branches to a Jira issue
How to link pull or merge requests to a Jira issue

How Commit Linking Works

Commits are selected by issue key. Developers should add them to comments every time they make commits.

For example, the “PRJ-50 fixed issue” comment – this assumes that you have configured a Jira project with the key ‘PRJ’ and someone has created the issue #50 within this project.

Example Git commit message: “TEST-1 Update…”
In this case, “TEST-1” is the issue key linking the commit message to the Jira issue.

Commits that are part of non-master branches are included only if the master branch doesn’t have them.

Best Practices for Linking

As a best practice when working with sub-tasks, put the parent and sub-task Jira issue keys in the commit message so that the commit shows in both places. This way, the commit for the sub-task does not get lost in the many commits of the parent issue.

The maximum commit message length limit is 8,000 characters.

Git Integration for Jira supports commits that used the old Jira key in the commit message after a project rename to a new key name (Example: TEST-16 to PROJ-16).

Two scenarios relate to the rename/move:

The Jira project key was renamed and the commit message contains the old key prior to installing Git Integration for Jira.
The Jira issue was moved from one project to another project and the message contains the old key prior to installing Git Integration for Jira.

Jira Activity Stream
Only commits linked to Jira issues appear in the Jira Activity Stream (not all commits in repositories).

Associating Git Commits Manually to Jira Issues

The process steps in this section apply to Jira Cloud instances with Git Integration for Jira installed.

To manually link a git commit to a Jira issue, access the Change commit issues feature from the following locations:

Issue page ➜ Git Commits tab ➜ click View Full Commit. Click the icon to modify commit associations.
Jira dashboard menu Apps ➜ Git Integration: Repository browser ➜ click a repository with git commits. Click the icon on the commit in the repository view.

Method 1: Using the Dropdown

Add, edit, or delete linked Jira issue keys in the Associated issues to commit field:

Click the dropdown arrow and select a Jira issue from the list.
The selected Jira issue is associated to the currently configured commit.
Repeat the same process to associate one or more Jira issues.
Click X to remove selected commit association(s).

Method 2: Type to Search

Type a Jira issue key or a word from a Jira issue summary and the list displays matching results.
Click a Jira issue from the list to associate it to the currently configured commit.
Repeat the same process to associate one or more Jira issues.
Click X to remove selected commit association(s).

Click Save to save the changes.

Jira administrators can add/remove any association(s).

Project administrators can add/remove any association(s) in that project.

The authors of the commit can add/remove the association if they have the View Development Tools access.

If the commit is associated with multiple Jira issues, you see the following:

In the above example, the selected commit is associated with Jira issues TEST-1 and TEST-4.

Saving the changes triggers a repository reindexing to show new associations.

How to Link Branches to a Jira Issue

Associate branches to a Jira issue by inserting the Jira issue key in the branch name when creating them.

Via Git Service (GitHub Example)

Create a branch and associate it to a Jira issue:

Select the master branch dropdown.
Enter a new branch name in the search box. Mention a Jira issue key in the name to associate it to the Jira issue.
Click the result to create the new branch.

Via Git Integration for Jira App

You can also do this via the Jira issue Git integration developer panel:

Open a Jira issue.
On the right sidebar, click Git Integration. This opens the Jira issue Git integration developer panel.
Click Create branch.
Select a repository.
Select the Source branch to use as base.
The Branch name is automatically generated from the issue summary with inserted Jira issue key.
Edit the proposed name but leave the Jira issue key as is, or accept the generated branch name as it is.

How to Link Pull or Merge Requests to a Jira Issue

Associate pull or merge requests to a Jira issue by inserting the Jira issue key in the pull request when creating them.

Via Git Service

Create a pull/merge request and associate it to a Jira issue:

Set base and compare as required. (branch to master)
Enter a new pull request title in the provided box. Mention a Jira issue key in the title to associate it to the Jira issue.
Mentioning a Jira issue key in the description also associates this pull request to the Jira issue.

Via Git Integration for Jira App

You can also do this via the Jira issue Git integration developer panel:

Open a Jira issue.
On the right sidebar, click Git Integration. This opens the Jira issue Git integration developer panel.
Click Create pull request or Create merge request (GitLab).
Select a repository.
Select the Source branch to use as base.
Select the Target branch to merge the source branch to.
The PR/MR name is automatically generated from the issue summary with inserted Jira issue key.
Edit the proposed name but leave the Jira issue key as is, or accept the generated name as it is.

Prev: Web linking

Next: Smart commits

Last updated: December 2025

Have feedback about this article? Did we miss something? Let us know!