What is the Smart Commits for Bitbucket Plugin?

The "Smart Commits for Bitbucket" add-on aims to execute Jira and Bitbucket actions from commit messages. Switching between IDE, Git client, Bitbucket or Jira takes time and should be avoided. Therefore, the most important actions (e.g. comments, time logs, transitions, pull requests and more) can be executed directly from special keywords in the commit message. The Smart Commits for Bitbucket add-on is an enrichment in your development process, because it saves time and increases the performance of your process. 

Each commit can define one or more specific actions via the commit message. These actions are executed when the change sets are pushed to the remote repository located in Bitbucket. After the change-sets are received in Bitbucket, Bitbucket will analyze the change-sets for some special keywords and associated parameters. If the add-on finds a valid key and parameter, the corresponding action will be performed.

Supported Bitbucket Action

The Add-on supports several key words to perform Bitbucket actions. So it is possible to execute the following actions just by adding some special keywords in the commit message.

  • Create pull requests: It is possible to create a pull request just with a magic keyword in the commit message.
  • Add comments to pull requests: If a pull request is available you can add comments to the pull request via commit message
  • Add reviewers to pull requests: Also it is possible to add reviewers to an existing pull request, just by a commit message key word
  • Keep or Unapprove pull requests: If a pull request is already approved and the pull request will be changed by a commit, you can define if the pull request should be unapproved or not.

Supported Jira Actions

The Add-on supports several key words to perform Jira actions. So it is possible to execute the following actions just by adding some special keywords in the commit message.

  • Add comments: If a valid Jira Issue Key is mentioned, you can add comments to issue via commit message
  • Add time logs:  Based on magic keys, you can log time to a referenced Jira-Issue.
  • Execute transitions: Also it is possible to change the status of the Jira-issue, just by triggering workflow actions with a magic key.


Supported Action

ActionApplicationSinceDescription
CommentJIRA+Bitbucket
initial

A comment can be created for JIRA or for Bitbucket with the keyword #comment. This keyword will create a comment to all related pull requests and additionally to issues. For creating issue comments the commit must be start with a sequence of valid JIRA issue references. The author of the comment will be the author of the commit. The date of the comment will be the date of the push action.

JIRA+Bitbucket
initial

The #comment keyword will create comments on JIRA issues and on Bitbucket pull requests. Sometimes it is needed to create only Bitbucket or only JIRA comments.

  • If only the JIRA issues should be commented, then the additional keyword @jira is needed. 
  • If only the Bitbucket pull-requests should be commented, then the additional keyword @stash or @bb is needed. 
JIRA1.1.0/2.1.0

Comments in Jira has visibility options. This visibility option can be set based on a magic keyword. If you will add a comment to the issue with the following commit message: #comment[Developer] my message

The comment will be visible for users in the project role "Developer" only.

WorklogJIRA
initial
Based on issue keys a work log action can be executed. The author of the worklog will be the author of the commit. The date of the worklog will be the date of the commit. #time 1d will log one day

JIRA3.0.0If a work log will be executed,  then the hook will return the tracking information of the issue. It returns the values original effort, remaining effort, time spent (issue: TEST-1 - original: 1w - spent: 1d - remain: 4d)
Add reviewerBitbucket
initial

If the changes are related to a pull-requests, it is possible to add reviewers to the pull-requests. With the magic keywords #reviewer @user it is possible to add the "user" to a existing pull request (the from branch needs to be the same branch as the branch you will push to remote)

Review ApprovalsBitbucket
initial

In general there are two possibilities for the handling of reviews which has been done already. In some cases it makes sense that the review and the approval has to be done again, in some cases it makes no sense to do the review again (e.g. just correct a typo). The Smart Commit plugin supports two strategies to handle this.

  • Keep-Strategy: This strategy is the default setting. If there is no special key word in the commit messages, all approvals will be removed. In some cases it is necessary to do a small change which do not need further reviews and approvals (like fixing a typo). In that case the default unapproval action can be prevent by the keyword #keep.
  • Unapprove-Strategy: In the case of a push all approvals will be kept always. A special keyword (#unapprove)in a commit message is needed to unapprove all approvals of a related pull request.


TransitionJIRA
initial

This command transitions an issue to a particular workflow state.  If a commit message contains a hashtag together with a valid transition name (e.g. #close), the smart commits action will be trigged and the issue will be moved to the next status. The transition name needs to be unique and fully qualified. See syntax examples.

Create Pull RequestBitbucket
initial

A a pull-request can be created via the keyword #pull. The pull command needs as parameter the target branch. If the command and a valid target branch is given, the hook will create a pull request (from: the branch which will be pushed - to: the branch, which is available via parameter).

Change assigneeJIRA1.1.0/2.1.0

During the workflow of an issue it is maybe needed to move the issue to a different assignee (e.g. development done, needs testing → assign test user) Via the action #assignee it is possible to change the assignee to the issue.

Set priorityJIRA1.2.0/2.2.0During the implementation of an issue, maybe you will discover, that the issue priority is not correct. In this case the Smart Commits Plugin allows you to change the prioritisation of the issue with the key word #prio (e.g. #prio major)
Set/Add fixed versionJIRA1.2.0/2.2.0During the implementation of an issue, you made need to add or set the fixed version of the issue. The key #fixedVersion allows you to add or set a version to the issue (e.g. #fixVersion+=1.0.0) 
Set/Add affected versionJIRA1.2.0/2.2.0During the implementation of an issue, you made need to add or set the affected version of the issue. The key #affectedVersion allows you to add or set a version to the issue (e.g. #affectedVersion+=1.0.0) 
Set/Add componentsJIRA1.2.0/2.2.0During the implementation of an issue, you made need to add or set the components of the issue. The key #component allows you to add or set a existing component to the issue (e.g. #component+=frontend) 
Set/Add labelsJIRA1.2.0/2.2.0During the implementation of an issue, you made need to add or set the labels of the issue. The key #label allows you to add or set a existing component to the issue (e.g. #label+=need-investigation) 
Add tasksBitbucket3.0.0During the implementation of an issue, you maybe know things the reviewer should be respect during the review (Maybe he/she should double check a special code change) For this you have the key word #task. With this keyword you can add a task to a pull-request. (#task please double check class xyz)
Remaining effortJIRA3.0.0When you implement an issue, you know best how long it will take to complete the issue. So you can also set the remaining time to the normal time bookings. With the keyword #remain you can set the remaining effort of an issue. (#remain 1d)



Syntax

Basic JIRA syntax

The basic syntax for JIRA commands is the following: 

<ISSUE_KEY> <ACTION> <COMMAND_PARAMETERS> ;


If you include the following text in your commit message, Bitbucket will record 2 days and 5 hours of work against issue TEST-1 and TEST-2. As you see you can enter also a list of issue keys. The actions defined will be executed for both issue keys. 

Example:


TEST-1 TEST-2 #time 2d 5h ;


Also it is possible to define a action context with a semicolon. With a semicolon you can define different actions for different JIRA issues. If you include the following text in your commit message, the plugin will record 2 days and 5 hours of work against the issue TEST-1 and TEST-2. Additionally Bitbucket will record 3 days to the issues TEST-3 and TEST-4. If there is no semicolon the complete commit message after the first issue keys will be parsed as one action context. In that case the second command regarding TEST-3 and TEST-4 will be ignored. A semicolon is recommended anyway.

Example:

TEST-1 TEST-2 #time 2d 5h ;
TEST-3 TEST-4 #time 3d ;


Also please note that commit actions can span more than one lines

Example:

TEST-1 #comment this is a comment
 over two lines ;

Syntax of actions

ActionSyntaxExampleDescription
Comment

#comment <text>

or

#comment @jira @stash<text>

#comment This is my

first example comment

Creates a comment to JIRA issues and Pull requests

#comment @jira

#comment @jira This is my

first example comment (only for Jira)

Creates a comment to JIRA issues and *not* to Pull requests

#comment @stash

#comment @stash This is my

first example comment (only for Bitbucket)

Creates a comment to Bitbucket pull requests and *not* to JIRA issues

#comment @jira[<role>]  #comment @jira[Developer] This is my secure commentCreates a comment, which is visible for users in the project role Developer only
Worklog#time <JIRA worlog syntax>

#time 2d 5h 30m

#time 4w 1d

Creates a work-log entry without work-log comment

Possible values:

  • weeks (w)
  • days (d)
  • hours (h)
  • minutes (m).
Worklog + Comment

#comment <text>

#time <JIRA worlog syntax>

#comment This is my

second example comment

#time 4w 1d

  • Creates a comment to the defined issue
  • Creates a work-log entry with work-log comment
  • Creates a comment to all related pull requests
Add Reviewer

#reviewer @<username1> @<username2>

 #reviewer @user1 user2

Condition: Pull request must be available 

Add the user1 and user2 to related and open pull-requests

Unapprove#keep/#unapprove

Condition: Pull request must be available

Depending on the unapproval strategy the related keeword will keep or remove all reviews of a related pull-request

Execute transition#<transition-name>

#start-progress

#stop-progress

#resolve

Triggers the given transition
Create pull-request#pull <brach-name>#pull master Creates a pull request from the current branch into the master branch
Assignee#assignee=<username>#assignee=adminChanges the assignee to the user admin
Set priority#prio=<prioritization> 

#prio=Major
#prio=blank-prio

Set prioritization "Major" to the issue TEST-1.
Set prioritization with blanks "blank prio" to the issue TEST-1

Blanks in the prioritization needs to be replaces with a minus "-"

Set/Add labels

#label+=<label-name>

#label=<label-name>

  1. #label+=newLabel
  2. #label=newLabel
  3. #label+=newLabel1 #label+=newLabel2
  1. Add the label "newLabel" to the issue
  2. Set the label "newLabel" to the issue. All existing labels will be overwritten
  3. Add the label "newLabel1" and "newLabel2" to the issue
Set/Add components

#component=<component-name>

#component+=<component-name>

  1. #component+=component1
  2. #component=component1
  3. #component+=component1 #component+=component2
  4. #component+=blank-component

Condition: Component must be available

  1. Add the component "component1" .
  2. Set the component "component1". All existing components will be overwritten
  3. Add the components "component1" and "component2"

  4. Add a component with blanks "blank component"

    Blanks in the component needs to be replaces with a minus "-"

Set/Add affected version

#affectedVersion+=<version>

#affectedVersion=<version>

  • #affectedVersion+=version1
  • #affectedVersion=version1
  • #affectedVersion+=version1 #affectedVersion += version2
  • #affectedVersion+=blank-version-1

Condition: Version must be available

  1. Add the affected version "version1"
  2. Set the affected version "version1". All existing versions will be overwritten
  3. Add the affected versions "version1" and "version2"

  4. Add a affected version with blanks "blank version 1" 

    Blanks in the version needs to be replaces with a minus "-"

Set/Add fixed version

#fixVersion+=<version>

#fixVersion=<version>

  1. #fixVersion+=version1
  2. #fixVersion=version1
  3. #fixVersion+=version1 #fixVersion+=version2
  4. #fixVersion+=blank-version-1


Condition: Version must be available

  1. Add the fixed version "version1" to the issue
  2. Set the fixed version "version1" to the issue. All existing components will be overwritten
  3. Add the fixed versions "version1" and "version2" to the issue TEST-1.

  4. Add a fixed version with blanks "blank version 1"

    Blanks in the version needs to be replaces with a minus "-"

Set remaining effort#remain <time>#remain 1w 1d

Condition: The value must be in the edit screen of the issue

It will set the remaining effort of a issue to 1 week and 1 day

Add task#task <task content><newline>

#task my new task

#task my second task

Condition: Pull request must be available

Add two tasks to the pull requests


Commit Examples


Commit messageResult

Comment and Worklog

TEST-1 TEST-2 
#comment @jira @stash Changes ready for review 
#time 2d
;
TEST-1 TEST-2 
#comment Changes ready for review 
#time 2d
;
  • Will produce a comment on the primary JIRA instance for issue TEST-1 and TEST2
  • Will log 2 day for the issue TEST-1 and TEST-2
  • Add a comment to each related pull request


Information

If the time tracking option is enabled, the push response will print the time tracking information of this issue

[INFO] [JIRA Worklog] Time tracking - (issue: TEST1-385 - original: 1w - spent: 1d - remain: 4d)  

Comment for JIRA and Bitbucket

#comment @jira @stash Changes ready for review
  • Because there is no JIRA issue, the @jira will be ignored.
  • Add a comment to each related pull request

Worklog

TEST-1 #time 1w 2d 3h;
    • Will log 1 week 2 days and two hours for the issue TEST-1
    • No comment will be added to the worklog

Multiple Issue actions 1

TEST-1 #time 1d;
TEST-2 #time 2d;
TEST-3 #time 3d;
  • Will log 1 day to issue TEST-1
  • Will log 2 days to issue TEST-2
  • Will log 3 days to issue TEST-3

Multiple Issue actions 2

TEST-1 #time 1d #comment first comment;
TEST-2 #time 2d #comment second comment;
TEST-3 #time 3d #comment third comment;
 
  • Will log 1 day to issue TEST-1 with the comment "first comment"
  • Will log 2 days to issue TEST-2 with the comment "second comment"
  • Will log 3 days to issue TEST-3 with the comment "third comment"
  • Will comment all relates pull request with the firth finding #comment or #comment @stash. In that case all pull requests will be commented with the string "first comment"

Additional Bitbucket comment

TEST-1 TEST-2 
#comment This is a jira and Bitbucket comment
#time 2d
; 
#comment @stash This is a Bitbucket comment only
  • Will produce a comment on the primary JIRA instance for issue TEST-1 and TEST2
  • Will log 2 day for the issue TEST-1 and TEST-2
  • Add a comment to each related pull request
  • Add a extra comment on each related pull request

Simple comment with unapprove

#comment The change needs a review again #unapprove
 
  • Add to all pull requests the comment "The change needs a review again"
  • In the case that the Unapprove-Strategy is configured, this commit message will unapprove all pull requests

Simple comment with keep

#comment The change needs no review 
#keep
 
 
  • Add to all pull requests the comment "The change needs no review"
  • In the case that the Keep-Strategy is configured, this commit message will keep all approvals of the pull requests

JIRA action with keep

TEST-1 TEST-2 
#comment The change needs no review 
#time 2d
#keep
;
  • Add a comment on the primary JIRA instance for issue TEST-1 and TEST2
  • Will log 2 day for the issue TEST-1 and TEST-2
  • Add a comment to each related pull request
  • Add to all pull requests the comment "The change needs no review"
  • In the case that the Keep-Strategy is configured, this commit message will keep all approvals of the pull requests

Add reviewer

TEST-1 TEST-2 
#comment @jira The final changes are done
#time 2d
;
#comment @stash Hey @user1 and @user2, please review my changes. Thx.
#reviewer @user1 @user2
  • Add a comment on the primary JIRA instance for issue TEST-1 and TEST2
  • Will log 2 day for the issue TEST-1 and TEST-2
  • Add a comment to each related pull request. Because of the mentions, the user1 and user2 will get a notification.
  • Add user1 and user 2 as reviewer to each related pull request
Execute transition
TEST-2 #Start-Progress #comment Comment for the transition #time 2h
  • Execute the transition "Start Progress" for the issue TEST-2
  • Will log 2 hours for the issue TEST-2
  • Add a comment to each related pull request and to the issue TEST-2
Create Pull-Request
TEST-2 #Start-Progress #comment Comment for the transition #time 2h
#pull master
#reviewer @user1 @user2
 
  • Create Pull-Request to master
  • Add to each related pull request the reviewers "user1" and "user2"
  • Execute the transition "Start Progress" for the issue TEST-2
  • Will log 2 hours for the issue TEST-2
  • Add a comment to each related pull request and to the issue TEST-2

Create task
TEST-2 #Start-Progress #comment Comment for the transition #time 2h
#pull master
#reviewer @user1 @user2
#task my first task
#task my second task
  • Create Pull-Request to master
  • Add to each related pull request the reviewers "user1" and "user2"
  • Execute the transition "Start Progress" for the issue TEST-2
  • Will log 2 hours for the issue TEST-2
  • Add a comment to each related pull request and to the issue TEST-2
  • Add a task "my first task" and "my second task" to the issue TEST-2
Remaining time
TEST-1 #comment @jira I need one day to finalise the issue #time 2h #remain 1d
  • Will log 2 hours for the issue TEST-2
  • Add a comment to the issue TEST-2
  • Set the remaining time of the issue TEST-2 to 1 day


Configuration

Since the version 3.0.0 the Smart Commit Plugin can be configured in the hook area of projects and/or repositories


Jira Actions

Each action can be enabled exclusive. So you can decide which actions you would like to use and which actions you would like to ignore.



Jira advanced settings

In addition, there is an advanced section where the configuration regarding issue-key detection rules and the Jira comment header can be done.


SettingsDescription
Issue-key regular expressionThe regular expression how issue keys will be detected. The default will fit in the most cases. But if you have special issue keys, you can modify the regular expression.
Jira Comment HeaderEnable a Jira comment header. This header will be added to each comment in Jira. You can add a link to the commit via the attribute $url, also you can add the repository $repo and the commit has $hash


Bitbucket Actions

In the same way as the Jira actions the Bitbucket actions can be enabled exclusive. So you can decide which actions you would like to use and which actions you would like to ignore.


Common advanced settings

In addition, there is an advanced section where the configuration regarding regarding the push response behaviour 


SettingsDescription
Enable Push Response

The result of the push will be printed as hook response. You can set the severity of the hook responses or you can disable the hook response. 

Information

If the push response is disabled, the hook will execute the smart actions in background and the push will come back directly.

Execution timeout

Even if the push response is enabled, the smart commit actions can run in the background. A time-out can be configured for this (milliseconds). As long as this timeout has not expired, the actions are executed normally and the executed actions generate the usual messages as push response. If there are still actions to be executed after the timeout, these actions are executed in the background and the "push" returns directly. (and prints only the already executed actions). 


All actions regarding Jira will be done via the primary application link.