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.3In 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
TST-1 #comment some comment
in Jira
on several lines
TST-1 #resolve
TST-2 #time 1h 30m
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 <email of Jira user>]ISSUE_KEY #fixversion [project version]ISSUE_KEY #affectsversion [project version]ISSUE_KEY(S) #label [label1] .. [labeln]Examples:
TST-123 #assign johnsmith
TST-123 #assign jsmith@example.comIn 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 implementedIn 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 Cloud | Jira Server |
|---|---|---|
| #comment | Yes | Yes |
| #time | Yes | Yes |
| #<transition> | Yes | Yes |
| #assign | Yes | Yes |
| #fixversion | No | Yes |
| #affectsversion | No | Yes |
| #label | Yes | No |
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
- Open an issue and click View Workflow from the context of the issue (near the issue’s Status).
- Hover a status. 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.
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.
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?
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
The Jira user must have the appropriate project permissions to transition issues.
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
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
To avoid conflict when transitioning issues, give a unique name to a workflow transition.
Smart Commit Helper
When Smart Commits setting is disabled for that repository, the Git add-on will not show the COMMIT indicators.
Multi-line Commit
Starting v2.6.33 of the Git Integration for Jira add-on, support for multi-line commit messages for Smart Commits has been implemented.
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.
