Smart Commits

Smart commits allows your team to perform actions on Jira issues from a single commit.  Users can enter the issue key and the desired action such as time tracking or closing an issue.

As of v2.6.3 of the Git add-on, the smart commit processing is active by default and can be enabled/disabled via the repository configuration (Actions > Edit repository settings):

Smart Commits setting

Smart Commits configuration checklist:

  • The Jira DVCS Connector Plugin is not required.
  • Your Jira e-mail address and Git commit e-mail address matches.
  • E-mail address is not shared by other Jira users.

v2.13.0Smart commits support project keys that has an underscore "_" character.

The Git Integration add-on supports smart commit by adding a simple syntax to a commit message.

The basic syntax for a Smart Commit message is:

<ISSUE_KEY> <ignored text> #<command> <optional command_params>
fyi
To know more about syntax, commands and examples on Smart Commits, see Processing Jira Software Issues with Smart Commit Messagesopen in new tab at the Atlassian website.

Basic Examples

There are Smart Commits commands that you can use in your commit messages.  Refer to the following table for more details on each smart commit command:

Command Usage and Description
#comment
The #comment command will add a comment to a Jira issue.
Syntax:
ISSUE_KEY #comment <your comment text>
Examples:
GIT-264 #comment Resolved conflicts.
GIT-1720 #comment Plugin version change from 2.8.2 to 2.8.3. Build number change from 69 to 70.
The above examples will add the specified comment text against the Jira issues.
warning
The committers’ email address in the git configuration must match with the email address of the corresponding Jira user (or vice versa) to comment on issues.
#time
The #time command will record time tracking information against a Jira issue.
Syntax:
ISSUE_KEY #time [Some amount in Jira time syntax] <Your worklog comment text>
Examples:
GIT-264 #time 1w 6d 13h 52m Total work logged.
GIT-1720 #time 1h 20m Merged to master. Released to marketplace.
The above examples will add the respective time and worklog comment text against the Jira issues.
warning
The Jira time tracking feature allows users to log the length of time spent working on issues.  Jira administrators must have enabled this feature for this smart commit to work.
#<transition-name>
The #<transition-name> command will move the Jira issue to a particular workflow state.
Syntax:
ISSUE_KEY #<transition-name> <Your comment text>
Examples:
GIT-264 #code-review For review.
GIT-1720 #close Tasks completed. Closing ticket.
The above examples will transition the Jira issues to their specified workflow state and add the comment to the respective Jira issues.
warning
The Jira user must have the appropriate project permissions to be able to transition issues.
#assign

INTRODUCED v2.9.7
The #assign command will assign the particular issue to the specified Jira user.
Syntax:
ISSUE_KEY #assign [<Jira username> or <email of Jira user>]
Examples:
GIT-1925 #assign johnsmith
GIT-1961 #assign jsmith@example.com
#fixversion

INTRODUCED v2.9.7
Jira Server Only
The #fixversion command will add a Fix Version/s details tag to the specified issue.
Syntax:
ISSUE_KEY #fixversion [project version]
Examples:
GIT-1628 #fixversion 2.9.6
Adds fix version tag 2.9.6 to the issue, GIT-1628.
GIT-1628 #fixversion 2.9.5 #fixversion 2.9.6
Adds fix version tags 2.9.5 and 2.9.6 to the issue, GIT-1628.
FYI
If there was an initial Fix Version tag on the specified issue, a #fixversion command will append the new Fix Version tag to it.
For example:
The Fix Version tag, 2.9.4, already exists in issue GIT-1254.  Performing a smart commit – GIT-1254 #fixversion 2.9.5 will give a result of:

Fix Version/s: 2.9.4, 2.9.5
#affectsversion

INTRODUCED v2.9.7
Jira Server Only
The #affectsversion command will add an Affect Version/s details tag to the specified issue.
Syntax:
ISSUE_KEY #affectsversion [project version]
Examples:
GIT-1582 #affectsversion 2.9.6

note
The #affectsversion command works the same way as #fixversion.  However, it appends Affect Version/s tag instead to the specified issue.
#label

INTRODUCED v2.12.6
Jira Cloud Only
The #label command will add a new label to a Jira issue.  If more than one Jira issue is referenced, the labels are added to all mentioned Jira issues.  Multiple labels can be created by putting spaces between words.
Syntax:
ISSUE_KEY(S) #label [label1] .. [labeln]
Examples:
GITCL-443 #label bucketbreakfix bucketenhancement
GITCL-443 GITCL-247 GITCL-214 #label admin@example.com user1@example.com requested-feature new-feature #comment Return email when implemented
warning
The #assign, #fixversion and #affectsversion commands are available only for Jira Server.  Jira Cloud support will be announced at a later date.

Advanced Examples

Usage and Description
A single action on a single issue.
Example:
TEST-100 #time 2w 1d 4h 30m This is a time log comment
Records the specified worklog #time of 2 weeks, 1 day, 4 hours and 30 minutes and adds worklog comment "This is a time log comment" to the issue, TEST-100.
Multiple actions on a single issue.
Example:
TEST-100 #time 4h 30m Fix null pointers #comment Fixed code #resolve
Logs specified #time of 4 hours and 30 minutes and add worklog comment "Fixed null pointers" to the issue, TEST-100; adds the #comment "Fixed code" and resolves the issue.
A single action on multiple issues.
Example:
TEST-100 TEST-101 TEST-102 #resolve
Resolves specified issues.
Multiple actions on multiple issues.
Example:
TEST-100 TEST-101 TEST-102 #resolve  #time 2d 4h #comment Fixed code
Resolves specified issues; logs specified #time of 2 days and 4 hours and adds #comment "Fixed code" against the issues.

Starting v2.6.33 of the Git Integration for Jira, support for multi-line commit messages for Smart Commits has been implemented. The following examples show correct usage of the Smart Commit message:

TST-1 implemented feature 1
TST-1 #comment some comment
in Jira
on several lines
TST-1 #resolve
TST-2 #time 1h 30m
In this example, an issue key that is present on every line is a valid multi-line commit message.
TST-1 implemented feature 1
#comment some comment
in Jira
on several lines
#resolve TST-2
#time 1h 30m
This is the equivalent smart commit message based from the above example.
TEST-3 Background color of settings should be lighter
TEST-3 #in-progress #time 1h TEST-4 resolve
TEST-2 #resolve
This example, containing several issue keys, is also a valid multi-line smart commit message.

Workflow Transitions

The simple Jira workflow does not contain explicit transition names.  These kind of workflow with no explicit transition names are becoming more popular as Atlassian is suggesting them to administrators upon project creation.

Jira simple workflow

The name of the status is the transition.  So, for the example above, the valid transitions from DONE are:

  • #to-do
  • #in-progress
  • #in-review
warning
Workflow transition names must be unique.
helpful tip
When there are no transition names — just use the status names.  If there is a space, replace it with "–" (hyphens).  For example, CODE REVIEW becomes #code-review.

Viewing Workflow

warning
Accessing the View workflow link on the Issue page requires a user or user group to have the View Read-Only Workflow project permissions.

You can see the available custom workflow transition commands for use with Smart Commits by doing the following:

  1. Open an issue and click View Workflow from the context of the issue (near the issue’s Status).
  2. Hover a status.
  3. When you hover a status - it will highlight available transitions.  This is the transition name that is used in Smart Commits and not the status name.

    Jira workflow transition hover status

Below is an example using the above workflow where the issue is in OPEN status and want to send it to BUSINESS SPEC status:

<ISSUE_KEY> #to-business-spec or,
<ISSUE_KEY> #to-business and even,
<ISSUE_KEY> #to> (yes, this works, as long as it does not conflict with another transition name)

If a smart commit fails, an email notification is sent to either the Jira user, or to the Git user if a Jira user can't be identified.

Smart Commits Helper

The smart commit helper is introduced in v2.9.3 of the Git add-on and is available at the following locations:

  • Issue > Commit Tab
  • Project Page > Git Commits
  • Repository Browser > Commits

A smart commit helper indicator is displayed to the right of the user/commit author:

Smart commits helper example
Status Description
COMMIT The Smart Commits setting is enabled for the repository but there is no smart commit keyword in the commit message.
SMART COMMIT The commit message has a valid smart commit structure and was successfully processed.
SMART COMMIT ERROR There was an error during smart commit processing.  For example, invalid keyword; commit author and Jira user are not the same; permission issues or wrong values.

The smart commit helper status are not shown:

  • for any smart commits that were made before Git add-on v2.9.3.
  • for smart commits that were ignored due to Smart Commits setting for that repository is disabled.
  • for smart commits that have not been processed yet.
  • for processed commits with ticket ID but without smart commit keyword when Smart Commits setting is disabled for that repository.
fyi
When Smart Commits setting is disabled for that repository, the Git add-on will not show the COMMIT indicators.

Refer to the commit message case examples below:

Commit ID Commit Message
Commit1
Merged to master
(This commit message does not contain an issue key)
Commit2
TST-1 Merged to master
(This commit message has an issue key but no smart commit keyword)
Commit3
TST-1 Merged to master #done
(This commit message have an issue key and valid smart commit keyword)
Commit4
TST-1 Merged to master #unknownSCkeyword
(This commit message has an invalid smart commit keyword)

When Smart Commits setting was set to ENABLED:

Commit ID Status after SC=Disabled Status after SC=Enabled
Commit1 Commit is ignored since issue key is not provided. Commit is ignored since issue key is not provided.
Commit2 No status indicator. COMMIT
Commit3 SMART COMMIT SMART COMMIT
Commit4 SMART COMMIT ERROR SMART COMMIT ERROR

When Smart Commits setting was set to DISABLED:

Commit ID Status after SC=Disabled Status after SC=Enabled
Commit1 Commit is ignored since issue key is not provided. Commit is ignored since issue key is not provided.
Commit2 No status indicator. No status indicator because it was marked as ignored.
Commit3 No status indicator. No status indicator because it was marked as ignored.
Commit4 No status indicator. No status indicator because it was marked as ignored.
note
The commit status shown on the Issue page depends on the Smart Commits setting that was set at the time the commits were processed.