This is the documentation for FishEye 4.0. View the latest version of

Unknown macro: {spacejump}

or visit the latest FishEye documentation home page.

Smart Commits allow repository committers to perform actions such as transitioning JIRA Software issues or creating Crucible code reviews by embedding specific commands into their 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 actions available if you use Crucible. See below for more information.

Each Smart Commit message must not span more than one line (i.e. you cannot use a carriage return in the command), but you can add multiple commands to the same line. See this example below.

 

On this page:

Related pages:

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

Description
Adds 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

Description

Records 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

Description

Transitions 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.

Smart Commit commands for Crucible reviews

When creating a new review using a Smart Commit the default project objectives are added to the review, and since Fisheye/Crucible 2.10.2, the commit message is also copied to the review objectives.

Note that you cannot add arbitrary objectives to the review using a Smart Commit.

Create a review

DescriptionCreate a review in Crucible.
Syntax
<commit message> +review <project key>
Example
Fix a bug +review CR-TEST
Notes

The +review  command creates a new review in the project CR-TEST with the content of the changeset. The review will be in a draft state unless the project has default reviewers or reviewers are explicitly mentioned. If you only have one project in Crucible, or a repository is a project's default repository, it is not necessary to mention the project key.

Add reviewers

DescriptionAdd reviewers when creating a new review in Crucible.
Syntax
<commit message> +review <project key> <reviewer_1> <reviewer_2>... <reviewer_n>
Example
Fix a bug +review CR-TEST @jcage @skhan
Notes

The command will create a new review in PROJ and add the users jcage and skhan to the review. The review will be automatically started if reviewers are specified.

Note that you cannot add reviewers to existing reviews using Smart Commits.

Update a review

Description Iteratively add new code changes to a review
Syntax
<commit message> +review <review key>
Example
Implement rework on past work +review CR-TEST-123
Notes

Often, reviews require rework and changes in response to comments left by the team. When committing these changes, adding the review key will iteratively add these new changes to the review.

Note that:

  • Each commit command in the Smart Commit must not span more than one line (i.e. you cannot use carriage returns). However, you can use multiple commands in the same commit message, and these can be on the same line.
  • Creating a review in Crucible using a Smart Commit requires that the author of the changeset has already been mapped to a Crucible username. See 'Author mapping' on Changing your user profile.

Advanced examples

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.

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 'Imagine that this is a really, and I', but drops the rest of the comment. The work time of 2 days and 5 hours is not logged against the issue because there is no issue key for the #time command in the second line. That is, each line in the commit message must conform to the Smart Commit syntax.

This example would work as expected if set out as:

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

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

Your FishEye administrator must have:

Note that:

  • Smart Commits only support the default JIRA Software issue key format (that is, two or more uppercase letters, followed by a hyphen and the issue number, for example BAM-123).
  • Smart Commits don't provide for field-level updates in JIRA Software issues.

  • When using Smart Commits you can use linkers that create a hyperlink to the JIRA Software issue. See Linkers for more information.

  • If there are any errors during the processing of Smart Commits, they will be logged to FishEye's error console, as well as emailed to the actioning users. Speak to your FishEye administrator about Configuring SMTP.

If the application link is configured as OAuth

If the application link to JIRA Software is configured to use OAuth, the committing user must authenticate with JIRA Software before any Smart Commit will work with JIRA Software.

  1. Create a test review in FishEye.
  2. Log in as the committing user.
  3. Open the review and click Edit Details.
  4. Enter a JIRA Software issue key for 'Linked Issue' and click Link. You'll be prompted to authenticate.
  5. Do this for every committing user (there's no need to create a new review, just link the review to any JIRA Software issue).
  • No labels
 

 

 

 

 Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.