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 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
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
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]
TST-123 #assign johnsmith TST-123 #assign firstname.lastname@example.org
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
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
GITCL-443 GITCL-247 GITCL-214 #label email@example.com firstname.lastname@example.org requested-feature new-feature #comment Return email when implemented
The name of the status is the transition. So, for the example above, the valid transitions from DONE are:
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.
The smart commit helper is introduced in v2.9.3 of the Git add-on and is available at the following locations:
A smart commit helper indicator is displayed to the right of the user/commit author.
|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:
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.
The Jira user must have the appropriate project permissions to transition issues.
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.
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.
To avoid conflict when transitioning issues, give a unique name to a workflow transition.
When Smart Commits setting is disabled for that repository, the Git add-on will not show the COMMIT indicators.
Starting v2.6.33 of the Git Integration for Jira add-on, support for multi-line commit messages for Smart Commits has been implemented.
The commit status shown on the Issue page depends on the Smart Commits setting that was set at the time the commits were processed.