Cloud
Data Center 8.21
Versions

Processing issues with Smart Commits

Working with issues

On this page

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

When you manage your project's repositories in Bitbucket or GitHub, or use Fisheye to browse and search your repositories, you can process your Jira Software issues using special commands, called Smart Commits, in your commit messages.

You can:

  • comment on issues
  • record time tracking information against issues
  • transition issues to any status defined in the Jira Software project's workflow

There are other commands available if you use Crucible for software reviews. See Using Smart Commits in the Crucible documentation.

A single Smart Commit command cannot span more than one line (i.e. you cannot use carriage returns in the commit message), but you can add multiple commands to the same line, or multiple commands on separate lines. See this example below.

On this page:

Smart Commit commands

The basic command line syntax for a Smart Commit message is:

<ignored text> <ISSUE_KEY> <ignored text> #<COMMAND> <optional COMMAND_ARGUMENTS>

Any text between the issue key and the Smart Commit command is ignored.

There are three Smart Commit commands you can use in your commit messages:

Comment

DescriptionAdds a comment to a Jira Software issue.
Syntax<ignored text> ISSUE_KEY <ignored text> #comment <comment_string>
Example
JRA-34 #comment corrected indent issue
Notes
  • The committer's email address must match the email address of a single Jira Software user with permission to comment on issues in that particular project.

Time

DescriptionRecords time tracking information against an issue.
Syntax<ignored text> ISSUE_KEY <ignored text> #time <value>w <value>d <value>h <value>m <comment_string>
Example
JRA-34 #time 1w 2d 4h 30m Total work logged
Notes

This example records 1 week, 2 days, 4 hours and 30 minutes against the issue, and adds the comment 'Total work logged' in the Work Log tab of the issue.

  • Each value for w, d, h and m can be a decimal number.
  • The committer's email address must match the email address of a single Jira Software user with permission to log work on an issue.
  • Your system administrator must have enabled time tracking on your Jira Software instance.

Workflow transitions

DescriptionTransitions a Jira Software issue to a particular workflow state.
Syntax<ignored text> ISSUE_KEY <ignored text> #<transition_name> <comment_string>
Example
JRA-090 #close Fixed this today
Notes

This example executes the close issue workflow transition for the issue and adds the comment 'Fixed this today' to the issue. Note that the comment is added automatically without needing to use the #comment command.

You can see the custom commands available for use with Smart Commits by visiting the Jira Software issue and seeing its available workflow transitions:

  1. Open an issue in the project.
  2. Click View Workflow (near the issue's Status).

The Smart Commit only considers the part of a transition name before the first space. So, for a transition name such as finish work, then specifying #finish is sufficient. You must use hyphens to replace spaces when ambiguity can arise over transition names, for example: #finish-work.

If a workflow has two valid transitions, such as:

  • Start Progress
  • Start Review

A Smart Commit with the action #start is ambiguous because it could mean either of the two transitions. To specify one of these two transitions, fully qualify the transition you want by using either #start-review or #start-progress.

  • When you resolve an issue with the #resolve command, you cannot set the Resolution field with Smart Commits.
  • If you want to add a comment during the transition, the transition must have a screen associated with it.
  • The committer's email address must match the email address of a single Jira Software user with the appropriate project permissions to transition issues.

Advanced examples

Multiple commands over multiple lines on a single issue

Syntax

<ISSUE_KEY> #<COMMAND_1> <optional COMMAND_1_ARGUMENTS> #<COMMAND_2> <optional COMMAND_2_ARGUMENTS> ... #<COMMAND_n> <optional COMMAND_n_ARGUMENTS>

Commit message

JRA-123 #comment Imagine that this is a really, and I 
mean really, long comment #time 2d 5h

Result

Adds the comment 'This is a really, and I' (but drops the rest of the comment) and logs 2 days and 5 hours of work against issue JRA-123.

Multiple commands on a single issue

Syntax

<ISSUE_KEY> #<COMMAND_1> <optional COMMAND_1_ARGUMENTS> #<COMMAND_2> <optional COMMAND_2_ARGUMENTS> ... #<COMMAND_n> <optional COMMAND_n_ARGUMENTS>

Commit message

JRA-123 #time 2d 5h #comment Task completed ahead of schedule #resolve

Result

Logs 2 days and 5 hours of work against issue JRA-123, adds the comment 'Task completed ahead of schedule',
and resolves the issue.

A single command on multiple issues

Syntax

<ISSUE_KEY1> <ISSUE_KEY2> <ISSUE_KEY3> #<COMMAND> <optional COMMAND_ARGUMENTS> etc

Commit message

JRA-123 JRA-234 JRA-345 #resolve

Result

Resolves issues JRA-123, JRA-234 and JRA-345.

Multiple issue keys must be separated by whitespace or commas.

Multiple commands on multiple issues

Syntax

<ISSUE_KEY1> <ISSUE_KEY2> ... <ISSUE_KEYn> #<COMMAND_1> <optional COMMAND_1_ARGUMENTS> #<COMMAND_2> <optional COMMAND_2_ARGUMENTS> ... #<COMMAND_n> <optional COMMAND_n_ARGUMENTS>

Commit message

JRA-123 JRA-234 JRA-345 #resolve #time 2d 5h #comment Task completed ahead of schedule

Result

Logs 2 days and 5 hours of work against issues JRA-123, JRA-234 and JRA-345, adds the comment
'Task completed ahead of schedule' to all three issues, and resolves all three issues.

Multiple issue keys must be separated by whitespace or commas.

Get Smart Commits working

It's easy to get Smart Commits working for your instance of Jira Software:

ToolConnection instructions
Bitbucket Server

Create an application link between Jira Software and Bitbucket Server. See Linking Bitbucket Server to Jira.

Then, enable smart commits in Jira Software: 

  1. Log in to Jira as a user with Jira administrator permissions.
  2. In the upper-right corner of the screen, select Administration  > Applications.
  3. Under Integrations, select Application links.
  4. Next to the application you want to configure, select Actions > Smart commits.
  5. Select the checkbox for the account you want to enable smart commits for.

FishEye

Create an application link between Jira Software and Fisheye. See Linking to another application.

Then, enable Smart Commits in Jira Software:

  1. Log in to Jira as a user with Jira administrator permissions.
  2. In the upper-right corner of the screen, select Administration  > Applications.
  3. Under Integrations, select Application links.
  4. Next to the application you want to configure, select Actions > Smart commits.
  5. Select the checkbox for the account you want to enable smart commits for.

Crucible

Create an application link between Jira Software and Crucible. See Linking to another application.

Then, enable Smart Commits in Jira Software:

  1. Log in to Jira as a user with Jira administrator permissions.
  2. In the upper-right corner of the screen, select Administration  > Applications.
  3. Under Integrations, select Application links.
  4. Next to the application you want to configure, select Actions > Smart commits.
  5. Select the checkbox for the account you want to enable smart commits for.

Bitbucket Cloud, GitHub

First, link your Jira Software and Bitbucket or GitHub accounts. See Connect Bitbucket Cloud to Jira Software Server and Linking GitHub accounts for details. 

Check if Smart Commits are enabled for new repositories:

  1. Log in to Jira as a user with Jira administrator permissions.
  2. In the upper-right corner of the screen, select Administration  > Applications.
  3. Under Integrations, select  accounts.
  4. Click the settings icon for the account.
  5. Select Enable Smart Commits on new repositories.

Enable or disable Smart Commits on individual repositories:

  1. Log in to Jira as a user with Jira administrator permissions.
  2. In the upper-right corner of the screen, select Administration  > Applications.
  3. Under Integrations, select  accounts.
  4. Select (or deselect) the Smart commits option for a repository. 

Notes

  • Smart Commits only support the default Jira Software issue key format. This format is two or more uppercase letters, followed by a hyphen and the issue number. For example, JRA-123.

  • A DVCS such as Git includes a user's email address in the commit data. Users configure this email address in their local system. Smart commits functionality requires that this email address matches exactly one email address in the Jira Software user base. If the email address matches multiple users in Jira Software, or the user does not have permissions for the requested action, the Smart commit action will fail. The commit itself will still succeed, and will show on the issue. Mismatched email addresses is a common reason why Smart commits fail to work as expected. If a Smart commit fails, Jira Software sends an email notification to either the Jira Software user or to the DVCS user (if a Jira Software user can't be identified). In rare cases, Jira Software doesn't have either of these email addresses, and the Smart commit fails silently.

  • Smart commits relies on the Jira DVCS Connector Plugin when your repositories are hosted in Bitbucket Cloud or GitHub. The plugin is bundled with Jira Software, but if necessary, a Jira administrator can install it directly from within the Jira administration area. To do this, go to Manage apps > Find new apps. See Installing Marketplace apps.
Last modified on Oct 11, 2022

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.