If you host project source repositories on Bitbucket or GitHub and use JIRA to track the projects' issues, you can process JIRA issues through commit messages. You can transition issues to any status define in a JIRA projects' workflow, comment on issues, and record time tracking information against issues. This feature is called smart commits.To use smart commits, you must have the JIRA DVCS Connector plugin installed. JIRA Cloud has the plugin already installed. For JIRA Server installations, install the free JIRA DVCS Connector plugin version 1.1 or above on your JIRA instance.
Understand the requirements of smart commits
To use smart commits, a user incorporates directives into commit messages. 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. For example, to record 2 days and 5 hours of work against issue JRA-123, a user includes the following line in a commit message:
JRA-123 #time 2d 5h
Users can include multiple smart commits directives in the same commit message.
DVCS systems include 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. Along with a match of the email address to a single JIRA user, the JIRA user must have permission to comment and resolve issues in that particular project. To use the
#time directive the user must have permission to log work on an issue.
If the email matches to multiple users in JIRA or the user does not have permissions, the smart commit function fails though the commit still shows on the issue. Mismatched email addresses is a common reason why smart commits fail to work as expected.
There are three commands you can use in your commit message.
ISSUE_KEY #time <value>w < value>d <value>h <value>m <comment_string>
Records time tracking information against an issue. The value must be a whole number. For example:
This example records 1 week, 2 days, 4hours and 30 minutes against an issue, and adds the comment '
Total work logged' in the Work Log tab of the issue.
For this command to work, your system administrator must have enabled time tracking on your JIRA instance.
ISSUE_KEY #comment <comment_string>
Records a comment against an issue. For example:
Adds the comment "
corrected indent issue" to the issue.
ISSUE_KEY #<transition> <comment_string>
Transitions an issue to a particular workflow state. For example:
Executes the close issue workflow transition for an issue. This transition is in the default JIRA workflow. The directive also adds the comment '
Fixed this today' to the issue.
transition values depend on a project's workflow configuration. To view a project's workflow, log into JIRA and do the following:
- Open an issue in the project.
- Locate the Status field in the Details section.
- Click the View Workflow link provided.
The smart commit works on the transition prefixes. This means if you have transition names with spaces, such as
finish work, then specifying
#finish is sufficient. Hyphens replace spaces:
#finish-work also matches.
Issue transitions work only if there is no ambiguity in valid workflow transitions. Suppose a workflow has two valid transitions:
A smart commit with action
#start is ambiguous because it could mean either of the two transitions. To execute one of these two transitions, fully qualify the transition you want by specifying either
- When you resolve an issue with the
#resolvedirective, you cannot set the Resolution field via smart commits.
- If you want to add a comment during the transition, the transition must have a screen associated with it.
A single action on a single issue
<ISSUE_KEY> #<CMD> <optional CMD_PARAMETERS>
Record 2 days and 5 hours of work against issue JRA-123:
JRA-123 #time 2d 5h
|Multiple actions on a single issue|
<ISSUE_KEY> #<CMD_1> <optional CMD1_PARAMETERS> #<CMD_2> <optional CMD2_PARAMETERS> ... #<CMD_n> <optional CMDn_PARAMETERS>
Example:Log 2 days and 5 hours of work against issue JRA-123, add the comment 'Task completed ahead of schedule' and resolve the issue:
JRA-123 #time 2d 5h #comment Task completed ahead of schedule #resolve
|Aa single action on multiple issues|
<ISSUE_KEY1> <ISSUE_KEY2> <ISSUE_KEY3> #<CMD> <optional CMD_PARAMETERS> etc
Example:Resolve issues JRA-123, JRA-234 and JRA-345:
JRA-123 JRA-234 JRA-345 #resolve
|Multiple actions on multiple issues|
<ISSUE_KEY1> <ISSUE_KEY2> ... <ISSUE_KEYn> #<CMD_1> <optional CMD1_PARAMETERS> #<CMD_2> <optional CMD2_PARAMETERS> ... #<CMD_n> <optional CMDn_PARAMETERS>
Example:Log 2 days and 5 hours of work against issues JRA-123, JRA-234 and JRA-345, add the comment 'Task completed ahead of schedule' to all three issues, and resolve all three issues.
JRA-123 JRA-234 JRA-345 #resolve #time 2d 5h #comment Task completed ahead of schedule