Set up Jira Cloud
Learn how to set up Jira Cloud and integrate it with other products and applications.
Process issues 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 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 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
The basic syntax for a Smart Commit message is:
<ignored text> <ISSUE_KEY> <ignored text> #<COMMAND> <optional COMMAND_ARGUMENTS>
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 Software issue. |
|---|---|
Syntax | <ignored text> <ISSUE_KEY> <ignored text> #comment <comment_string> |
Example | 1
JRA-34 #comment corrected indent issueJRA-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 issues in that particular project. |
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 | 1
JRA-34 #time 1w 2d 4h 30m Total work loggedJRA-34 #time 1w 2d 4h 30m Total work logged |
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.
|
Workflow transitions
Description | Transitions a Jira Software issue to a particular workflow state. |
|---|---|
Syntax | <ignored text> <ISSUE_KEY> <ignored text> #<transition_name> #comment <comment_string> |
Example | 1
JRA-090 #close #comment Fixed this todayJRA-090 #close #comment Fixed this today |
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:
You can see the custom commands available for use with Smart Commits by visiting the Jira Software issue and looking at its available workflow transitions:
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:
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.
|
View development information on your Jira issues
To view linked development information in a Jira issue:
Navigate to the issue.
Under Development, select the number of pull requests, branches, or commits to see additional information.
Advanced examples
Multiple commands on a single issue
Syntax | 1
<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 | 1
JRA-123 #time 2d 5h #comment Task completed ahead of schedule #resolveJRA-123 #time 2d 5h #comment Task completed ahead of schedule #resolve |
Result | Logs 2 days and 5 hours of work against issue JRA-123, adds the comment 'Task completed ahead of schedule', |
Multiple commands over multiple lines on a single issue
Syntax | 1
<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 | 1
JRA-123 #comment Imagine that this is a really, and I JRA-123 #comment Imagine that this is a really, and I
1
mean really, long comment #time 2d 5hmean 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 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: 1
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
1
JRA-123 #time 2d 5hJRA-123 #time 2d 5h |
A single command on multiple issues
Syntax | 1
<ISSUE_KEY1> <ISSUE_KEY2> <ISSUE_KEY3> #<COMMAND> <optional COMMAND_ARGUMENTS> etc <ISSUE_KEY1> <ISSUE_KEY2> <ISSUE_KEY3> #<COMMAND> <optional COMMAND_ARGUMENTS> etc |
|---|---|
Commit message | 1
JRA-123 JRA-234 JRA-345 #resolveJRA-123 JRA-234 JRA-345 #resolve |
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 | 1
<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 | 1
JRA-123 JRA-234 JRA-345 #resolve #time 2d 5h #comment Task completed ahead of scheduleJRA-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 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 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 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 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 issue. 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:
1
2
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.
Was this helpful?
Still need help?
The Atlassian Community is here for you.