Site announcement

We are switching off article comments on this website. Read about the upcoming changes to Atlassian Documentation.

Skip to end of metadata
Go to start of metadata

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.

Note that:

  • Multiple smart commits can be used in one commit message, however each smart commit must be on a separate 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:

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.

 Click to see how to authenticate with JIRA...
  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 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 issue).

On this page:

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 that JIRA 5.0, with JIRA FishEye Plugin versions earlier than 5.0.10.

Transition your JIRA issues

Basic command line syntax

The basic command line syntax for your commit comment is:

<ISSUE_KEY> #<COMMAND> <optional COMMAND_PARAMETERS>

For example, if you include the following text in your commit message, FishEye will record 2 days and 5 hours of work against issue JRA-123, when you perform your commit:

Please 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 JRA-123.

(info) Please 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. Please note that a commit command cannot span more than one line (i.e. you cannot use carriage returns), and separate commands must be on separate lines.

  • To perform multiple actions on a single issue:

<ISSUE_KEY> #<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 issue JRA-123, add the comment 'Task completed ahead of schedule' and resolve the issue, when you perform your 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 your commit message, FishEye will resolve issues JRA-123, JRA-234 and JRA-345, when you perform your 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 your commit:

Commands

Note that 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).

 

Command

Command Parameters

Description

Example

#time

<n>w <n>d <n>h <n>m <work log comment> 
where <n>  is a user-specified value.

This command records time tracking information against an issue.
Please note, time tracking must be enabled for your JIRA instance to use this command. Please check with your JIRA administrator, if you cannot record time tracking information against issues.

Please note that Work log comments cannot be set using smart commits. See FE-3757.

#time 1w 2d 4h 30m Total work logged — this command would record 1 week, 2 days, 4hours and 30 minutes against an issue, and add the comment 'Total work logged' in the Work Log tab of the issue.

 

#comment

<comment text>

This command records a comment against an issue.

#comment My comment. — this command would create the comment, "My comment", against the issue.

#<workflow command>
e.g. #resolve

<workflow> <comment text> 

This command transitions an issue to a particular workflow state. Please see the documentation for  Configuring Workflow  in JIRA.

FishEye will do prefix matching for issue transitioning. For example, if you have transition name with spaces, such as finish work then specifying #finish is sufficient. Hyphens replace spaces: #finish-work

FishEye will only execute issue transitions if there is no ambiguity in valid workflow transitions. Take the following example:
An issue has two valid transitions:

  • Start Progress
  • Start Review

A smart commit with action #start is ambiguous as FishEye will not be able to determine which transition to execute. In order to execute one of these transitions, the smart commit specified will need to be fully qualified #start-review

Please note: If you want to resolve an issue using the #resolve command, you will not be able to set the resolution via smart commits. We are tracking this improvement request here: FE-3873 - Smart Commits: Cannot set the resolution when using the "#resolve" command Open

#close Fixed the issue — this command would execute the 'Close Issue' workflow transition for an issue in the default JIRA workflow and adding the comment 'Fixed the issue'.
#start — this command would execute the 'Start Progress' workflow transition for an issue in the default JIRA workflow

Integration with Crucible

Please note that:

  • 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 also easy to create a Crucible review from a commit:

The command "+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".

Adding reviewers

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, you cannot add reviewers to existing reviews using smart commits.

Review objectives

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 from the 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.

Linkers

When using smart commits you can use linkers that create a hyperlink to the JIRA issue. See Linkers for more information.

Error handling

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. Please speak to your FishEye administrator about Configuring SMTP.

  • No labels

35 Comments

  1. Anonymous

    can we update a field in the issue using smart commits?

    1. Smart commits don't provide for field-level updates. You could write your own plugin to do this, however.

  2. Is there an escape sequence for putting a hashtag/number sign (#) in a commit without it being interpreted? One of our developers used one and Fisheye attempted to interpret it as a workflow command. (It failed, which wasn't a problem, but it emailed him an error and he was confused.)

    1. Anonymous

      Clear a good idea to add an escape sequence. The current workmode is too limited there...

  3. How can I update a issue and create a new review without adding 'garbage' to the review title?

    If I have a commit log that looks a bit like this:

    I'll get a name containing the JIRAISSUE-XX #workflowcommand #time etc...

    1. Are there any updates to what Da an is indicating? We are running into the same issue. Here is the format I have tried (we are  committing this command via GIT Tower and then pushing it to GIT):

      Nice descriptive title text JIRAISSUE-XXX #workflowcommand #time 1d 2h 3m #comment Info specific to JIRA progress +review CR-TEST @me @you @us

      This sets the Crucible title and objectives text as:

      Nice descriptive title text JIRAISSUE-XXX #workflowcommand #time 1d 2h 3m #comment Info specific to JIRA progress

      Not very nice as a result.

      Resolution?

       

      1. Anonymous

        When resolving issues and adding comments with smart commit, then I've experienced that newline delimits different blocks. Does it not work the same when creating review?

        We don't use review creating with smart commits, but wishful thinking tells me, that, when you put your +review in commit messages new line, then it should be interpreted separately. (maybe try with extra linefeed before +review or try putting +review onto first line instead)

      2. The following should work:

        Nice Review Title and/or Objectives +review CR-TEST @me @you @us
        JIRAISSUE-123 #worflowcommand #time 1d 2h 3m #comment Info specific to JIRA progress 

         

         

        1. Thanks Brendan! Is there a way to separate the "Nice Review Title" and the "Objectives" ie how does FishEye/Crucible know where the title ends and the objectives begin? 

        2. I have it exactly like that, but that does not seem to work.

          The smart commit is logged against Jira, but no review is created.

  4. Is there a way to create a review using smart commit message commands so that the review immediately goes to the closed state? Something like:

    +review CR-TEST reviewed by @buddy


    In cases where the code is already peer reviewed when it is time to commit, it would be beneficial if you could use Crucible's reporting mechanisms to track those reviews without needing to open the web-interface. Maybe a confirmation from the reviewer listed in the commit message should be required.

    1. You can't currently do this, but I like the idea. I've created  CRUC-6489 - smart commit plugin: support creation of closed reviews Open  to track the request - please watch that issue for updates. 

  5.  

    Any chance that Smart Commits will ever handle names like BAM123-123? We have an e-mail from Bryan Rollins back in March 2013:

    "We've decided that we will re-introduce support for numbers and underscores in JIRA project keys, after feedback from a number of customers.  It's been clear from feedback from customers like yourself that numbers and underscores will handle 99% of the cases out there and shouldn't complicate it for integrations to JIRA.  So don't change your project keys if they only contain numbers and letters (and underscores)."

    As we noted back in our original e-mails in March, we have a lot of project names with numbers.

     

    1. Hello Broadcom,

      In the example your provided ("BAM123-123") is that the issue reference (project key - issue number) or just the project key? Hyphens are not allowed in the project key per this announcement:

       End of Support Announcements for JIRA, RE: project key

      Please open a Support Request if the project key doesn't contain a hyphen and the Smart Commit doesn't work.

       

  6. "BAM123" is the project key with both alpha and numeric, "-123" is the issue. See the "Compatiblity" Info box near the top of this page:

    "Note that 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)."

    Perhaps for distinction, we should now use "BAM987-123" so we don't confuse the "123"s

  7. how soon will a review be created after a smart commit?  I tried three commits.  noticed only one review is created.

  8. Anonymous

    How can I add a reviewer that has a space in username? e.g. +review @john-doe 

    1. Usernames can only contain alphanumeric, underscore, at ('@'), dot, dash or backslash characters

  9. Anonymous

    Smart commits connect an issue to one or more commits, such that for example those commits show up in JIRA if I ask for "source" related to an issue.

     

    Suppose something has been committed without this naming convention. Is there any way to manually link "change X" to "JIRA issue Y"? Say, something in the JIRA or FishEye UIs?

  10. Is it possible to set the security / viewing info for the work log during the commit? - Thank you!

  11. Anonymous

    Is it possible to use smart commit and tell it to create one review request for Crucible for several commits at once?

  12. We are using git PRE-COMMIT whereby patch is submitted for review and once review has been completed the changeset will be committed to the SCM reposiroty. We would like to use Fisheye to track review coverage, how do we do it in this scenario? How do we indicate or link closed crucible review with a changeset so that  we know the code changes has been reviewed.

  13. We are using git PRE-COMMIT whereby patch is submitted for review and once review has been completed the changeset will be committed to the SCM reposiroty. We would like to use Fisheye to track review coverage, how do we do it in this scenario? How do we indicate or link closed crucible review with a changeset so that  we know the code changes has been reviewed.

  14. Anonymous

    Any chance on getting the SVN revision number as a command?  For instance:

    #comment Bug fixed in version #svn

    which would add this JIRA comment:

    "Bug fixed in version 12345"

  15. This seems to be a serious issue with trying to use the #time functionality with git:

    DCON-313 - Merge commit messages result in duplicate time entries in JIRA when using Smart Commits. Open

    Has anyone else run accross this or found a usable workaround?

  16. Anonymous

    Hi. I want to create a review on a SVN commit. I've tried to use below in SVN log for the check in. But It does not work. Did I miss something?

    Doing a smart commit test by a svn checking in.  +review LRN-REVIEW @reviewer

  17. I did the same as the previous Anonymous with Crucible smart commit enabled, but it doesn't work. Anything wrong?

    Updated xxxx. +review Forms @reviewer

  18. Is this feature only available on hosted solutions, or should this be able to work on locally installed versions too?  (i.e. bitbucket/jira/fisheye vs stash/jira/fisheye)

  19. The setup to process JIRA issues with commit messages was not easy. In my case there were two problems. 

    First make sure that you can access FishEye code snippets from JIRA AND that you can open JIRA issues from Fisheye. The last one didn't work cause of authentication problems. Also make sure that you setup users in FishEye and use the "user mapping" feature to map your svn or whatever users to your fisheye users. If you don't do that, you get no errors! My fisheye log contained no errors, but smart commits didn't work either. If you do the user mapping stuff, you get helpful error mails!

    The second problem in my setup was that JIRAs Remote IP must be enabled. I read all the docs that are about connecting JIRA and FishEye and the setup for smart commits, but didn't read anything about the Remote API part.

    After that everything works like a charm (smile)

  20. When will this horribly broken feature be fixed?

  21. Hi all, I have got a requirement that, there should be a pre-commit svn hook which blocks developers from committing without entering the open-JIRA ticket in the comment. If the commit doesnot contain any open-JIRA ticket, commit should not be happen. Please help. I have tried pre-commits in svn . However, I am unable to edit and add this requirement. 

    1. Hi Samuel, may I suggest that you open this up to the FishEye community on Atlassian Answers, using the 'fisheye' tag?

    2. hi Samuel, what you probably want is to have a script which you execute from svn's pre commit hook.  the script that parses commit message for JIRA issue keys, then connects to your JIRA to validate the keys.  you could, for eg, use https://jira-python.readthedocs.org/en/latest/ library.

  22. Can we have Crucible set-up in a way to automatically commit the changes that were being reviewed to git?

     

    Consider the following:

    1-I make changes to my abcde.java class and add a few white spaces

    2-I use crucible.py to create a review and add reviewers like @jdoexxxxx

    3-The user, jdoexxxxx reviews the changes and completes it

    4-The moderator sees that its completed and therefore he closes the review

    Now, can I set Crucible up in a way where it'd automatically commit the proposed changes without the developer having to commit those changes only?

     

     

    1. Hi morteza hafez,

      I am afraid FishEye/Crucible currently does not modify indexed repositories in any manner, it simply accesses those repositories in read only manner.  It is an interesting feature you are asking for, but I can't see such feature to be implemented in Crucible in the foreseeable future.   This idea is similar to pull requests known from DVCS like git or mercurial.  If you want to play with them, you may find that both Atlassian Stash and Atlassian Bitbucket offer automated branch merging on pull request approval.