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 work items using special commands, called Smart Commits, in your commit messages.
You can:
comment on work itemss
record time tracking information against work items
transition work items 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:
<ignored text> <WORK_ITEM_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 work item. |
---|---|
Syntax |
|
Example | JRA-34 #comment corrected indent work item |
Note | The committer's email address must match the email address of a single Jira user with permission to comment on work items 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 work items 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 work item. |
---|---|
Syntax |
|
Example | 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 '
|
Workflow transitions
Description | Transitions a Jira work item to a particular workflow state. |
---|---|
Syntax |
|
Example | 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 ' There are some exceptions to this syntax:
You can see the custom commands available for use with Smart Commits by visiting the Jira work item 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 If a workflow has two valid transitions, such as:
A Smart Commit with the action
|
Advanced examples
Multiple commands on a single work item
Syntax | <WORK_ITEM_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 |
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 work item
Syntax | <WORK_ITEM_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 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 # 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 #time 2d 5h |
A single command on multiple work items
Syntax | <WORK_ITEM_KEY1> <WORK_ITEM_KEY2> <WORK_ITEM_KEY3> #<COMMAND> <optional COMMAND_ARGUMENTS> etc |
---|---|
Commit message | 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 | <WORK_ITEM_KEY1> <WORK_ITEM_KEY2> ... <WORK_ITEM_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 |
Result | Logs 2 days and 5 hours of work against work items JRA-123, JRA-234 and JRA-345, adds the comment 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:
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 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'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 work item. 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?