• Documentation

Jira is getting a fresh new look and navigation

We’re in the process of rolling out these changes and the documentation may not match your experience. Bear with us while we update it to reflect the new changes. More about navigating the new Jira

Process work items with smart commits

When you manage your project repositories in Bitbucket or GitHub, or use Fisheye to browse and search your repositories, you can process your Jira Software work items using special commands, called Smart Commits, in your commit messages.

You can:

  • comment on work items

  • record time tracking information against work items

  • transition work items to any status defined in the software project workflow.

There are other actions available if you use Crucible for software reviews. See Using Smart Commits in the Crucible documentation.

A Smart Commit command must not span more than one line (i.e. you cannot use carriage returns in the command), but you can add multiple commands to the same line. See this example below.

Smart Commit commands

In smart commit commands, ‘issue’ refers to a work item. What is a work item?

The basic syntax for a Smart Commit message is:

<ignored text> <ISSUE_KEY> <ignored text> #<COMMAND> <optional COMMAND_ARGUMENTS>

Any text between the work item key and the command is ignored.

There are three commands you can use in your Smart Commit messages:

  • comment

  • time

  • transition

Comment

Description

Adds a comment to a Jira Software work item.

Syntax

<ignored text> <ISSUE_KEY> <ignored text> #comment <comment_string>

Example

JRA-34 #comment corrected indent issue
JRA-34 #comment corrected indent issue

Notes

The committer's email address must match the email address of a single Jira Software user with permission to comment on work items in that particular project.

Time

Description

Records time tracking information against a work item.

Syntax

<ignored text> <ISSUE_KEY> <ignored text> #time <value>w <value>d <value>h <value>m <comment_string>

Example

JRA-34 #time 1w 2d 4h 30m Total work logged
JRA-34 #time 1w 2d 4h 30m Total work logged

Notes

This example records 1 week, 2 days, 4 hours and 30 minutes against the work item, and adds the comment 'Total work logged' in the Work Log tab of the work item.

  • The values for w, d, h and m can be decimal numbers.

  • The comment is added automatically without needing to use the #comment command.

  • The committer's email address must match the email address of a single Jira Software user with permission to log work on a work item.

  • Your system administrator must have enabled time tracking on your Jira Software instance.

Workflow transitions

Description

Transitions a Jira Software work item to a particular workflow state.

Syntax

<ignored text> <ISSUE_KEY> <ignored text> #<transition_name> #comment <comment_string>

Example

JRA-090 #close #comment Fixed this today
JRA-090 #close #comment Fixed this today

Notes

This example executes the close work item workflow transition for the work item and adds the comment 'Fixed this today' to the work item. 

 

There are some exceptions to this syntax:

  • If your Jira admin has set comment as a required field, you must not add #comment to the command

  • If any other fields have been set as required the transition command will silently fail.

You can see the custom commands available for use with Smart Commits by visiting the Jira Software work item and looking at its available workflow transitions:

  1. Open a work item in the project.

  2. Click View Workflow (near the work item Status).

The Smart Commit only considers the part of a transition name before the first space. So, for a transition name such as finish work, then specifying #finish is sufficient. You must use hyphens to replace spaces when ambiguity can arise over transition names, for example: #finish-work.

If a workflow has two valid transitions, such as:

  • Start Progress

  • Start Review

A Smart Commit with the action #start is ambiguous because it could mean either of the two transitions. To specify one of these two transitions, fully qualify the transition you want by using either #start-review or #start-progress.

  • When you resolve a work item with the #resolve command, you cannot set the Resolution field with Smart Commits.

  • The committer's email address must match the email address of a single Jira Software user with the appropriate project permissions to transition work items.

View development information on your Jira work items

To view linked development information in a Jira work item:

  1. Navigate to the work item.

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

Advanced examples

Multiple commands on a single work item

Syntax

<ISSUE_KEY> #<COMMAND_1> <optional COMMAND_1_ARGUMENTS> #<COMMAND_2> <optional COMMAND_2_ARGUMENTS> ... #<COMMAND_n> <optional COMMAND_n_ARGUMENTS>
<ISSUE_KEY> #<COMMAND_1> <optional COMMAND_1_ARGUMENTS> #<COMMAND_2> <optional COMMAND_2_ARGUMENTS> ... #<COMMAND_n> <optional COMMAND_n_ARGUMENTS>

Commit message

JRA-123 #time 2d 5h #comment Task completed ahead of schedule #resolve
JRA-123 #time 2d 5h #comment Task completed ahead of schedule #resolve

Result

Logs 2 days and 5 hours of work against work item JRA-123, adds the comment 'Task completed ahead of schedule',
and resolves the work item.

Multiple commands over multiple lines on a single issue

Syntax

<ISSUE_KEY> #<COMMAND_1> <optional COMMAND_1_ARGUMENTS> #<COMMAND_2> <optional COMMAND_2_ARGUMENTS> ... #<COMMAND_n> <optional COMMAND_n_ARGUMENTS>
<ISSUE_KEY> #<COMMAND_1> <optional COMMAND_1_ARGUMENTS> #<COMMAND_2> <optional COMMAND_2_ARGUMENTS> ... #<COMMAND_n> <optional COMMAND_n_ARGUMENTS>

Commit message

JRA-123 #comment Imagine that this is a really, and I 
JRA-123 #comment Imagine that this is a really, and I 

 

mean really, long comment #time 2d 5h
mean really, long comment #time 2d 5h

Result

Adds the comment 'Imagine that this is a really, and I', but drops the rest of the comment. The work time of 2 days and 5 hours is not logged against the work item because there is no work item key for the #time command in the second line. That is, each line in the commit message must conform to the Smart Commit syntax.

This example would work as expected if set out as:

JRA-123 #comment Imagine that this is a really, and I mean really, long comment 
JRA-123 #comment Imagine that this is a really, and I mean really, long comment 

 

JRA-123 #time 2d 5h
JRA-123 #time 2d 5h

A single command on multiple work items

Syntax

<ISSUE_KEY1> <ISSUE_KEY2> <ISSUE_KEY3> #<COMMAND> <optional COMMAND_ARGUMENTS> etc
<ISSUE_KEY1> <ISSUE_KEY2> <ISSUE_KEY3> #<COMMAND> <optional COMMAND_ARGUMENTS> etc

Commit message

JRA-123 JRA-234 JRA-345 #resolve
JRA-123 JRA-234 JRA-345 #resolve

Result

Resolves work items JRA-123, JRA-234 and JRA-345.

Multiple work item keys must be separated by whitespace or commas.

Multiple commands on multiple work items

Syntax

<ISSUE_KEY1> <ISSUE_KEY2> ... <ISSUE_KEYn> #<COMMAND_1> <optional COMMAND_1_ARGUMENTS> #<COMMAND_2> <optional COMMAND_2_ARGUMENTS> ... #<COMMAND_n> <optional COMMAND_n_ARGUMENTS>
<ISSUE_KEY1> <ISSUE_KEY2> ... <ISSUE_KEYn> #<COMMAND_1> <optional COMMAND_1_ARGUMENTS> #<COMMAND_2> <optional COMMAND_2_ARGUMENTS> ... #<COMMAND_n> <optional COMMAND_n_ARGUMENTS>

Commit message

JRA-123 JRA-234 JRA-345 #resolve #time 2d 5h #comment Task completed ahead of schedule
JRA-123 JRA-234 JRA-345 #resolve #time 2d 5h #comment Task completed ahead of schedule

Result

Logs 2 days and 5 hours of work against work items JRA-123, JRA-234 and JRA-345, adds the comment 'Task completed ahead of schedule' to all three work items, and resolves all three work items.

Multiple work item keys must be separated by whitespace or commas.

Get Smart Commits working

It's easy to get Smart Commits working for your instance of Jira Software:

Tool

Connection instructions

Bitbucket Cloud

First, link your Jira Software and Bitbucket accounts. See Connect Jira Cloud to Bitbucket Cloud.

Then, enable Smart Commits in Jira Software. See Enable Smart Commits.

GitHub

First, link your Jira Software and GitHub accounts. See Connect Jira Cloud to GitHub.

Then, enable Smart Commits in Jira Software. See Enable Smart Commits.

Fisheye

Create an application link between Jira Software and Fisheye. See Linking to another application.

Then, enable Smart Commits in Jira Software. See Enable Smart Commits.

Crucible

Create an application link between Jira Software and Crucible. See Linking to another application.

Then, enable Smart Commits in Jira Software. See Enable Smart Commits.

Notes

  • Smart Commits only support the default Jira Software work item key format. This format is two or more uppercase letters, followed by a hyphen and the work item number, for example JRA-123. 

  • A DVCS such as Git includes a user email address in the commit data. Users configure this email address in their local system. Smart Commits requires that this email address match exactly one email address in the Jira Software user base. If the email address matches to multiple users in Jira Software, or the user does not have permissions for the requested action, the Smart Commit action will fail. The commit itself will succeed however, and will show on the work item. Mismatched email addresses is a common reason why Smart Commits fail to work as expected. If a Smart Commit fails, Jira Software sends an email notification to either the Jira Software user, or to the DVCS user (if a Jira Software user can't be identified). In rare cases, Jira Software doesn't have either of these email addresses, and the Smart Commit fails silently.

  • Smart commit commands that you execute will appear duplicated under certain circumstances. Altering commit history creates "new" commits, which replace the "old" ones. If those "new" commits contain the same smart commit commands as before the history rewrite, then the same smart commits will be executed again and hence appear to have been duplicated. The commit history altering git commands include git push --force and git merge --squash.

  • Earlier Bitbucket was not sending the merge commit flag to Jira during event delivery. So ‘Smart commits’ was treating all commits as regular commits. Now, CommitEvent send to EventDelivery contains COMMIT_MERGED flag. Hence, use the below default merge commit format:

Merged in <branch name> (pull request #<PR id>) <PR title>
Merged in <branch name> (pull request #<PR id>)
<PR title>

It is recommended not to add the smart commit commands to the PR title that gets added to the merge commit message after merge. Instead, manually edit the merge commit message to get the smart commits working again.

 

 

Still need help?

The Atlassian Community is here for you.
Ask the Community
On this pageSmart Commit commandsCommentTimeWorkflow transitionsView development information on your Jira work itemsAdvanced examplesMultiple commands on a single work item Multiple commands over multiple lines on a single issueA single command on multiple work itemsMultiple commands on multiple work itemsGet Smart Commits workingNotes
CommunityQuestions, discussions, and articles