git plugin logo flat Git Integration for Jira. See Git commits in Jira.

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:

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.

The basic syntax for a Smart Commit message is:

<ISSUE_KEY> <ignored text> #<command> <optional command_params>

Using the format above, the smart commit structure will actually look like this:

TST-123 #comment fixed bug #time 1h 30m Bug fixes #fixversion release2.3
In the above example, the commit is associated to TST-123, adds the comment "fixed bug" to the Issue > Comment tab, logs the time of 1 hour and 30 minutes with worklog comment "Bug fixes", and adds fix version "release2.3" to the issue.

For multi-line commit messages, the following examples show correct usage of the Smart Commit message:

TST-1 implemented feature 1
#comment some comment
in Jira
on several lines
#resolve
TST-2 #time 1h 30m
The above example is a valid multi-line commit message.

The #assign, #fixversion and #affectsversion smart commit commands are introduced in v2.9.7 of the Git add-on with the following syntax:

<ISSUE_KEY> #assign [Jira username or Jira email address]
<ISSUE_KEY> #fixversion [project version]
<ISSUE_KEY> #affectsversion [project version]

Usage:

TST-123 #assign johnsmith
TST-123 #assign jsmith@example.com
In the above examples:
The first smart commit line uses the Jira username to assign issue TST-123 to that user.
The second smart commit line uses the Jira user's email address to assign issue TST-123 to that user.
TST-456 #fixversion 2.9.6
TST-456 #fixversion 2.9.5 2.9.6
TST-456 #fixversion 2.9.5 #fixversion 2.9.6
In the above examples:
The first example will apply the FixVersion 2.9.6 to the TST-456 issue.
The second example will apply the FixVersion 2.9.5 2.9.6 to the TST-456 issue.
The third example will apply the FixVersion(s) 2.9.5 and 2.9.6 to the TST-456 issue.
TST-789 #affectsversion 2.9.6
TST-789 #affectsversion 2.9.5 2.9.6
TST-789 #affectsversion 2.9.5 #affectsversion 2.9.6
In the above examples:
The first example will apply the AffectsVersion 2.9.6 to the TST-789 issue.
The second example will apply the AffectsVersion 2.9.5 2.9.6 to the TST-789 issue.
The third example will apply the AffectsVersion(s) 2.9.5 and 2.9.6 to the TST-789 issue.

Workflow Transitions

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

Viewing Workflows

  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

Smart Commit 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.

Did you know?

Need to know more?  Read further at  Documentation: Smart Commits