Use Smart Commits

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

You can:

comment on issues
record time tracking information against issues
transition issues to any status defined in the Jira project's 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, as shown in the Advanced examples > Multiple commands on a single line example below.

Smart Commit commands

The basic syntax for a Smart Commit message is:

Any text between the issue 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 issue.
Syntax	<ignored text> <ISSUE_KEY> <ignored text> #comment <comment_string>
Example
Note	The committer's email address must match the email address of a single Jira user with permission to comment on issues in that particular project

More information when using Github

The email address in Github must match the email address of a single Jira user with permission to comment on issues in that particular project

In Github, do not check Keep my email addresses private for smart commits to work properly

Time

Description	Records time tracking information against an issue.
Syntax	<ignored text> <ISSUE_KEY> <ignored text> #time <value>w <value>d <value>h <value>m <comment_string>
Example
Notes	This example records 1 week, 2 days, 4 hours and 30 minutes against the issue, and adds the comment 'Total work logged' in the Work Log tab of the issue. 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 user with permission to log work on an issue. Your system administrator must have enabled time tracking on your Jira instance.

Workflow transitions

Description	Transitions a Jira issue to a particular workflow state.
Syntax	<ignored text> <ISSUE_KEY> <ignored text> #<transition_name> #comment <comment_string>
Example
Notes	This example executes the close issue workflow transition for the issue and adds the comment 'Fixed this today' to the issue. 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 issue and looking at its available workflow transitions: Open an issue in the project. Click View Workflow (near the issue's 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 an issue 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 user with the appropriate project permissions to transition issues.

Advanced examples

Multiple commands on a single issue

Syntax
Commit message
Result	Logs 2 days and 5 hours of work against issue JRA-123, adds the comment 'Task completed ahead of schedule', and resolves the issue.

Multiple commands over multiple lines on a single issue

Syntax

Commit message

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 issue because there is no issue 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:

A single command on multiple issues

Syntax

Commit message

Result

Resolves issues JRA-123, JRA-234 and JRA-345.

Multiple issue keys must be separated by whitespace or commas.

Multiple commands on multiple issues

Syntax

Commit message

Result

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

Multiple issue 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:

Tool	Connection instructions
Bitbucket Cloud	First, link your Jira and Bitbucket accounts. See Connect Jira Cloud to Bitbucket Cloud. Then, enable Smart Commits in Jira. See Enable Smart Commits.
GitHub	First, link your Jira and GitHub accounts. See Connect Jira Cloud to GitHub. Then, enable Smart Commits in Jira. See Enable Smart Commits.
Bitbucket Data Center	Create an application link between Jira and Bitbucket Data Center. See Linking Bitbucket Data Center to Jira. Then, enable Smart Commits in Jira. See Enable Smart Commits.
Fisheye	Create an application link between Jira and Fisheye. See Linking to another application. Then, enable Smart Commits in Jira. See Enable Smart Commits.
Crucible	Create an application link between Jira and Crucible. See Linking to another application. Then, enable Smart Commits in Jira. See Enable Smart Commits.

Notes

Smart Commits only support the default Jira issue key format. This format is two or more uppercase letters, followed by a hyphen and the issue number, for example JRA-123.
A DVCS such as Git includes a user's 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 user base. If the email address matches multiple users in Jira, 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 issue. Mismatched email addresses is a common reason why Smart Commits fail to work as expected. If a Smart Commit fails, Jira sends an email notification to either the Jira user, or to the DVCS user (if a Jira user can't be identified). In rare cases, Jira doesn't have either of these email addresses, and the Smart Commit fails silently.

Was this helpful?

It wasn't accurate

It wasn't clear

It wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community