Smart commits allow repository committers to perform actions such as transitioning JIRA issues or creating Crucible code reviews by embedding specific commands into their commit messages.
- Multiple smart commits can be used in one commit message (and these can be on the same line).
- Smart commits only support the default JIRA 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 issues.
Your FishEye administrator must have:
- Enabled smart commits in FishEye. See Enabling smart commits.
- Configured an application link between FishEye/Crucible and JIRA. See Linking to another application.
If the application link is configured as OAuth
If the application link to JIRA is configured to use OAuth, the committing user must authenticate with JIRA before any smart commit will work with JIRA.
- Create a test review in FishEye.
- Log in as the committing user.
- Open the review and click Edit Details.
- Enter a JIRA issue key for 'Linked Issue' and click Link. You'll be prompted to authenticate.
- Do this for every committing user (there's no need to create a new review, just link the review to any JIRA issue).
Compatibility with JIRA
- In order to use smart commits with JIRA you need to have the JIRA FishEye Plugin version 3.4.5 or later installed on your JIRA instance.
- A project/entity link between FishEye/Crucible and JIRA is only required for JIRA versions earlier than JIRA 5.0, with JIRA FishEye Plugin versions earlier than 5.0.10.
Transition your JIRA issues
Basic command line syntax
The command line syntax for a commit comment is:
<ISSUE_KEY> #<COMMAND> <optional COMMAND_PARAMETERS>
For example, if you include the following text in the commit message, FishEye will record 2 days and 5 hours of work against issue JRA-123, when you perform the commit:
Note that commit commands cannot span more than one line (i.e. you cannot use carriage returns). For example:
will give the expected result, but
will only add 'this is' as a comment to the issue
See the section below for further information about command line parameters.
Advanced command line syntax
You can perform multiple actions on issues by combining commands. Note that a commit command cannot span more than one line (i.e. you cannot use carriage returns), but you can add multiple commands to the same line.
- To perform multiple actions on a single issue:
<ISSUE_KEY> #<COMMAND1> <optional COMMAND1_PARAMETERS> #<COMMAND2> <optional COMMAND2_PARAMETERS> #<COMMAND3> <optional COMMAND3_PARAMETERS>
For example, if you include the following text in the commit message, FishEye will log 2 days and 5 hours of work against issue JRA-123, add the comment 'Task completed ahead of schedule' and resolve the issue, when you make the commit:
- To perform a single action on multiple issues:
<ISSUE_KEY1> <ISSUE_KEY2> <ISSUE_KEY3> #<COMMAND> <optional COMMAND_PARAMETERS> etc
For example, if you include the following text in the commit message, FishEye will resolve issues JRA-123, JRA-234 and JRA-345, when you perform the commit:
- To perform multiple actions on multiple issues:
<ISSUE_KEY1> <ISSUE_KEY2> <ISSUE_KEY3> #<COMMAND1> <optional COMMAND1_PARAMETERS>
#<COMMAND2> <optional COMMAND2_PARAMETERS>
#<COMMAND3> <optional COMMAND3_PARAMETERS> etc.
For example, if you include the following text in your commit message, FishEye will log 2 days and 5 hours of work against issues JRA-123, JRA-234 and JRA-345, add the comment 'Task completed ahead of schedule' to all three issues, and resolve all three issues, when you perform the commit:
Note that there must be at least one leading space before
#<command>, even if the command begins a new line.
You can see the custom commands available for use with smart commits by visiting the JIRA issue and seeing its available workflow transitions (in an issue, click View Workflow, near the issue status).
<n>w <n>d <n>h <n>m <work log comment>
This command records time tracking information against an issue.
Note that Work log comments cannot be set using smart commits. See FE-3757.
This command records a comment against an issue.
<workflow> <comment text>
This command transitions an issue to a particular workflow state. See Configuring Workflow in JIRA.
FishEye will do prefix matching for issue transitioning. For example, if you have transition name with spaces, such as
FishEye will only execute issue transitions if there is no ambiguity in valid workflow transitions. Take the following example:
A smart commit with action
Note that to resolve an issue using the
Integration with Crucible
- Each commit command in the commit message must not span more than one line (i.e. you cannot use carriage returns). You can use multiple commands in the same message as long as they are on separate lines.
- 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.
Creating a review
With smart commits, it is easy to create a Crucible review from a commit:
+review tells FishEye to create 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. Just use
"fix a bug +review".
Reviewers can be added to a new review using a smart commit:
That 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.
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.
Updating an existing review
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:
With this command FishEye will add the changeset content to the review CR-TEST-123.
When using smart commits you can use linkers that create a hyperlink to the JIRA 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.