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.

v2.6.3+ The smart commit processing is active by default and can be enabled/disabled via the git configuration page (Actions > Edit integration settings):

In Jira Server, Smart Commits is a setting toggle in the Connect Wizard or the git
configuration page under Actions > Edit Integration Settings.
In Jira Cloud, this setting is always enabled.

Smart Commits configuration checklist:

  • The Jira DVCS Connector Plugin is not required.
    The Git Integration for Jira app has the functions of the connector plugin plus more integration support and features.
  • Your Jira e-mail address and Git commit e-mail address matches.
    The commit author's email should match exactly with a user's email in Jira. If they do not match, the application will add the commit as the app.
  • E-mail address is not shared by other Jira users.
    Verify that this email address is used by only one Jira user.
  • Advanced: Verify that the workflow conditions and validators are able to process successfully.

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]
v2.12.6+ <ISSUE_KEY(S)> #label [label1] .. [labeln]

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.
GITCL-443 GITCL-247 GITCL-214 #label admin@example.com user1@example.com requested-feature new-feature #comment Return email when implemented
In the above examples:
Adds the specified labels to Jira issues GITCL-443, GITCL-247 and GITCL-214;
then adds the comment text to those Jira issues.

Platform Support:

Command Jira Server Jira Cloud
#comment
#time
#<transition>
#assign
#fixversion
#affectsversion
#label *
* – Jira Server functionality will be added at a later date.

Workflow Transitions

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.

note
Commit authors:
Only letters and "-" (dash) are valid for workflow transition names for Smart Commits. Any other characters are treated as invalid. Smart Commits will ONLY use the valid characters before the occurrence of an invalid character for processing.
note
Jira Administrators:
When adding transitions in the Workflow editor, make transition names simple and easy to remember. Only use letters and only one space between words.

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.

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?

user permissions

Jira User

The committers’ email address in the git configuration must match with the email address of the corresponding Jira user (or vice versa) for the smart commit to work.

project permissions

Project Permissions

The Jira user must have the appropriate project permissions to transition issues.

workflow transitions

Workflow Transition

When you hover a status on the Issue Workflow - it will highlight available transitions.  This is the transition name that is used in Smart Commits.

email notification

Email Notification

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

transition names

Transition Names

To avoid conflict when transitioning issues, give a unique name to a workflow transition.

smart commit helper

Smart Commit Helper

When Smart Commits setting is disabled for that repository, the Git add-on will not show the COMMIT indicators.

multiline commits

Multi-line Commits

Starting v2.6.33 of the Git Integration for Jira add-on, support for multi-line commit messages for Smart Commits has been implemented.

Related topic...

smart commit status

Smart Commits Status

The commit status shown on the Issue page depends on the Smart Commits setting that was set at the time the commits were processed.

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