Page tree
Skip to end of metadata
Go to start of metadata

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.

On this page:

Related pages:

Enabling DVCS smart commits

 

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.

The commands

There are three commands you can use in your commit message. 

time Command

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:

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

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.

comment Directive

ISSUE_KEY #comment <comment_string>

Records a comment against an issue.  For example:

JRA-34 #comment corrected indent issue

Adds the comment "corrected indent issue" to the issue.

<transition> Directive

ISSUE_KEY #<transition> <comment_string>

Transitions an issue to a particular workflow state.  For example:

JRA-090 #close Fixed this today

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. 

The available transition values depend on a project's workflow configuration. To view a project's workflow, log into JIRA and do the following:

  1. Open an issue in the project.
  2. Locate the Status field in the Details section.
  3. 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:

  • Start Progress
  • Start Review

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 #start-review or #start-progress.

Notes:

  • When you resolve an issue with the #resolve directive, 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.

Advanced Examples

DescriptionSyntax

A single action on a single issue

<ISSUE_KEY> #<CMD> <optional CMD_PARAMETERS>

Example:

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

 

 

  • No labels