Documentation

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.

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

v3.2.0+ Smart commits support for all alphabet characters.

v3.5.0.2+ The Git Integration for Jira app supports case insensitive Smart Commits.

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 Git Integration app 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>

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:

#comment

This command works both in Jira Server/Cloud. 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.

#time

This command works both in Jira Server/Cloud. 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.

#<transition-name>

This command works both in Jira Server/Cloud. The #<transition-name> command will move the Jira issue to a particular workflow state.

Syntax:

ISSUE_KEY #<transition-name> <Your commit comment text>

Examples:

GIT-264 #code-review For review.

GIT-1720 #close Closing ticket. #comment Tasks completed.

The first example will transition the Jira issue to the specified workflow state and adds the comment message to the commit.

The second example will transition the Jira issue to the specified workflow state, adds the comment message to the commit, and adds specified the #comment to the Jira issue.

For more information on transitions and workflow names and how they work, see Workflow Transitions on this page.

#assign

This command works both in Jira Server/Cloud. 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

This command only works in Jira Server. It does not work in Jira Cloud. 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.

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

This command only works in Jira Server. It does not work in Jira Cloud. 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

#label

This command works both in Jira Server/Cloud.

v2.12.6+ Available in Jira Cloud

v3.5+ Available in Jira Server

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:

ISSUE_KEY(S) #label bucketbreakfix bucketenhancement

ISSUE_KEY(S) #label admin@example.com user1@example.com requested-feature new-feature #comment Return email when implemented

Advanced examples

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 app, 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.

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

• #to-do
• #in-progress
• #in-review

Viewing Workflow

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.

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.

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)

Do note that invalid characters can be used in the transition name. Jira accepts most of them and they can be used. However, smart commits will only process letters and dash characters.

Thus, the part of the transition name up to the invalid character can be used for transitions; where spaces become "-".

Example 1:

There must be at least one unique way to call each transition name. If you have multiple transition names from a single status that use the same word, the Smart Commits will fail.

Example 2: Another example, where an issue status "NEW" has these two transition paths:

• SEND_TO_DEVELOPMENT
• SEND_TO_BACKLOG

The invalid characters are used before unique transition names are possible. Both will become "#SEND". Therefore, they are not unique and these transitions will fail.'

Example 3: Finally, the transition names have spaces instead:

• SEND TO DEVELOPMENT
• SEND TO BACKLOG

Both of these transitions are Smart Commit friendly and the possible transitions are:

• #SEND-TO-D...
• #SEND-TO-B...

The "..." indicates the truncation with the least character length to have the transition names be recognized as unique by Smart Commits. Any length shorter than this will fail the transition as explained in Example 2 above.

Smart Commits Helper

v2.9.3+ Introduced the smart commit helper 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:

The smart commit helper status are not shown:

• for any smart commits that were made before V2.9.3 of Git Integration for Jira app.
• 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.

Refer to the commit message case examples below:

Merged to master 

TST-1 Merged to master

TST-1 Merged to master #done

TST-1 Merged to master #unknownSCkeyword

When Smart Commits setting was set to ENABLED:

When Smart Commits setting was set to DISABLED:

Smart Commits Settings

Max commit age – Set a limit (in days) for Smart Commit processing. Commits older than the Max commit age can be associated to the Jira issue but any Smart Commit commands will not be processed. This protects against cases where old commits are merged into a new repository.

Max commit age – This setting is a hidden feature in Git Integration for Jira Cloud and Dev Info for Jira Cloud. All commits which are older than this setting (in seconds) shall be ignored for smart commits processing. The default value is 1209600 seconds (14 days).