Page tree
Skip to end of metadata
Go to start of metadata

If you host project source repositories on Bitbucket or GitHub and use JIRA to track the projects' issues, you can process JIRA issues through commit messages. You can transition issues to any status define in a JIRA projects' workflow, comment on issues, and record time tracking information against issues. This feature is called smart commits.

To use smart commits, you must have the JIRA DVCS Connector plugin installed. JIRA Cloud has the plugin already installed.  For JIRA Server installations, install the  free JIRA DVCS Connector plugin version 1.1 or above on your JIRA instance.

On this page:

Related pages:

Enabling DVCS smart commits

 

Understand the requirements of smart commits

To use smart commits, a user incorporates directives into commit messages. Smart commits only support the default JIRA issue key format. This format is two or more uppercase letters, followed by a hyphen and the issue number, for example JRA-123.    For example, to record 2 days and 5 hours of work against issue JRA-123, a user includes the following line in a commit message:

JRA-123 #time 2d 5h

Users can include multiple smart commits directives in the same commit message. 

DVCS systems include a user's email address in the commit data. Users configure this email address in their local system. Smart commits requires that this email address match exactly one email address in the JIRA user base.  Along with a match of the email address to a single JIRA user, the JIRA user must have permission to comment and resolve issues in that particular project. To use the #time directive the user must have permission to log work on an issue.

If the email matches to multiple users in JIRA or the user does not have permissions, the smart commit function fails though the commit still shows on the issue. Mismatched email addresses is a common reason why smart commits fail to work as expected.

The commands

There are three commands you can use in your commit message. 

time Command

ISSUE_KEY #time <value>w <                                                                                                                                                                                                                                                                                                               value>d <value>h <value>m  <comment_string

Records time tracking information against an issue.  The value must be a whole number. For example:

JRA-34 #time 1w 2d 4h 30m Total work logged

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

Icon

For this command to work, your system administrator must have enabled time tracking on your JIRA instance.

comment Directive

ISSUE_KEY #comment <comment_string>

Records a comment against an issue.  For example:

JRA-34 #comment corrected indent issue

Adds the comment "corrected indent issue" to the issue.

<transition> Directive

ISSUE_KEY #<transition> <comment_string>

Transitions an issue to a particular workflow state.  For example:

JRA-090 #close Fixed this today

Executes the close issue workflow transition for an issue. This transition is in the default JIRA workflow.  The directive also adds the comment 'Fixed this today' to the issue. 

The available transition values depend on a project's workflow configuration. To view a project's workflow, log into JIRA and do the following:

  1. Open an issue in the project.
  2. Locate the Status field in the Details section.
  3. Click the View Workflow link provided.

The smart commit works on the transition prefixes. This means if you have transition names with spaces, such as finish work, then specifying #finish is sufficient. Hyphens replace spaces: #finish-work also matches.

Issue transitions work only if there is no ambiguity in valid workflow transitions. Suppose a workflow has two valid transitions:

  • Start Progress
  • Start Review

A smart commit with action #start is ambiguous because it could mean either of the two transitions. To execute one of these two transitions, fully qualify the transition you want by specifying either #start-review or #start-progress.

 

Icon

When you resolve an issue with the #resolve directive, you cannot set the Resolution field via smart commits.

 

Advanced Examples

DescriptionSyntax

A single action on a single issue

<ISSUE_KEY> #<CMD> <optional CMD_PARAMETERS>

Example:

Record 2 days and 5 hours of work against issue JRA-123:

JRA-123 #time 2d 5h
Multiple actions on a single issue
<ISSUE_KEY> #<CMD_1> <optional CMD1_PARAMETERS> #<CMD_2> <optional CMD2_PARAMETERS> ... #<CMD_n> <optional CMDn_PARAMETERS>

Example:

Log 2 days and 5 hours of work against issue JRA-123, add the comment 'Task completed ahead of schedule' and resolve the issue:
JRA-123 #time 2d 5h #comment Task completed ahead of schedule #resolve
Aa single action on multiple issues
<ISSUE_KEY1> <ISSUE_KEY2> <ISSUE_KEY3> #<CMD> <optional CMD_PARAMETERS> etc

Example:

Resolve issues JRA-123, JRA-234 and JRA-345:
JRA-123 JRA-234 JRA-345 #resolve
Multiple actions on multiple issues
<ISSUE_KEY1> <ISSUE_KEY2> ... <ISSUE_KEYn> #<CMD_1> <optional CMD1_PARAMETERS> #<CMD_2> <optional CMD2_PARAMETERS> ... #<CMD_n> <optional CMDn_PARAMETERS>

Example:

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.
JRA-123 JRA-234 JRA-345 #resolve #time 2d 5h #comment Task completed ahead of schedule

 

 

21 Comments

  1. Anonymous

    Have you considered using git notes to include commands instead of having commit message with hash tags which is a bit noisy?

  2. Anonymous

    Obviously as alternative, not really a replacement.

  3. Every time we rebase the commit messages get applied again. So if the original commit moves it to Review workflow state and then our QA reviews it and moves it to Done workflow state, the next time the branch is rebased the commit message is applied again and it is yanked out of Done workflow state and put back into Review. Any way around this?

    1. Anonymous

      Has anyone determined if this is a real issue, if so, is there a work around?

    2. Anonymous

      Can anyone confirm or deny? We're evaluating On Demand, and this would be a serious impediment to our adopting it.

      1. The important thing here is to make sure your workflows are set up with transition states that won't cause this to happen.  For example, if your workflow looks like this:  In Progress --> (Submit) --> QA Review --> (Approve) --> Done, and you don't have a transition from "Done" to "QA Review" named Submit, then you can use "JRA-123 #submit" and it will not move it back to QA Review because there is no valid transition state from "done" named "Submit".  

        1. And what if, in the meantime, the ticket was moved back to "In progress"?

  4. Anyone else having issues where the commit is linked to the issue, but the command are not processing the issue? Working with a GitHub organization account and its private repos

    1. It's working fine for our organization with JIRA On Demand, we also use Github private repos.  Do comments come through to the ticket(#comment) and only actions aren't taken to move the issue through the workflow?  Are you sure you are using the proper syntax for the workflow action?  The command syntax is taking the text from the button you would press in JIRA, convert to all lower case and separate spaces ' ' with hyphens '-' and precede with a hash '#' (e.g. if the button in JIRA says "Start Progress" the git commit message command would be #start-progress.

       

      Also be sure that your git config (on your develop machine git install and/or your git GUI client) email address for all the repos you're using JIRA for matches the email you use for your JIRA user.  If you're seeing comments come through ok this should already be good to go.

      1. Anonymous

        Also be sure that your git config (on your develop machine git install and/or your git GUI client) email address for all the repos you're using JIRA for matches the email you use for your JIRA user.  If you're seeing comments come through ok this should already be good to go.

        This was a big help - my git email didn't match my JIRA email, so even though the commit showed up, the comments and commands weren't showing up. Thanks!

        1. I was having this same issue I fixed my email addresses (did indeed have mismatched ones). The commit message is showing up but I'm still not able to comment/close/add time to issue. Any suggestions?

  5. Can you do this on regular self hosted git repos?

  6. Anonymous

    Leaves much to be desired. I'm not even sure the example given

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

     

    would work. Mine get truncated with just

    MYID-123 #time 1d 5h #comment This is some commen

    then gets chopped.  I think git wants the summary (first) line to be 50chars or less.   which means the example would look like

    JRA-123 JRA-234 JRA-345 #resolve #time 2d 5h #com

     

    1. Anonymous

      You want to write a regular short git commit message on the first line. Then put your relevant JIRA issue tracking/resolving/commenting command on a new line after the initial git commit line.

  7. Anonymous

    You are correct.  I realized that the restriction can be summarized as...

    1.  Only single lines get parsed. Not multi line.
    2. Summary line must be < 50 chars
    3. Description lines must be < 72 chars
    4. You can reuse the same ISSUE_KEY on as many lines as needed.

    So this is valid:

     

    This is my summary line. Succinct description here.

     

    Verbose commit description here..blah blah blah

    blah blah blah blah blah blah blah blah blah

    blah blah blah blah blah blah blah blah blah

     

    JRA-123 #comment This comment line must be < 72 chars or it gets truncated. NO multi line comment either.

    JRA-123 #time 1d 4h

    JRA-123 #close Fixed

     

  8. Anonymous

    I was hoping that there would be a way to only show commit messages against a JIRA item when those commits reaches a certain branch. If I am working on a feature branch as created for that JIRA item, I might not want them to show up in JIRA. Ideally I'd only want the commits to show up once those commits have reached develop or master. Is that possible?

  9. I was hoping during code reviews (either on Github, Bitbucket, Crucible or other integrated tool), if we add "comments" to a commit or diff, those could also be treated as "smart commit" triggers.

    In addition, it would be awesome to be able to either create new issues with a special command (or link to an existing issue to create sub-tasks), i.e.:

     

    JRA-123 #create Sub task title goes here

    This way we can track "actions" generated from code review directly onto JIRA without having to resort to going over all comments and creating individual issues or subtasks by hand. Was going to try and write my own plugin for it but given we're currently using the OnDemand service, it wouldn't work anyways, so I thought I'd send it as a feature request to the product team?

    1. Just found this from Crucicle's documents: Creating JIRA issues from the review

      That is what I mean, but basically triggered from 'smart comments'.

      1. Hi Roberto,

        The functionality that you've described doesn't exist. Please feel free to raise your idea as a feature request here: https://jira.atlassian.com/

        Kind regards,
        Andrew

  10. Is the plug-in intended to work along with JIRA Agile Simplified Workflow where there are no transitions? I am trying #close and #resolve but it does not seem to work since there are no transitions by those names.

    1. Is there a "View Workflow" button next to the current status on an issue?  It will show the name of the transitions, though I don't know enough about JIRA Agile Simplified or whether it has that button.