Skip to main content
Skip table of contents

User Guide 2.3.x



What is the Smart Commits for Bitbucket Plugin?

Smart Commits allows users over commits to execute special actions during the development. Each commit can define one or more special actions. This actions will be executed if the change sets will be pushed to the remote repository, which is located in Bitbucket. After the change sets has been received in Bitbucket, Bitbucket will parse the change-sets regarding some special keywords and related parameters. If the parser will find a valid key and parameters, the corresponding action will be executed. Actions can relate to all Atlasssian products like JIRA or Bitbucket. 


Supported Action

ActionApplicationSinceDescription
Comment
 		JIRA+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 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

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.
Add reviewerBitbucket
initial
If the changes are related to a pull-requests, it is possible to add reviewers to the pull-requests
Review ApprovalsBitbucket
initial

In general there are to possibilities for the handling of reviews which has been done already. Pull requests which has been approved already needs is some cases that the review and the approval has to be done again. 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. A special keyword 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.  The smart commits will need to be fully qualified. See syntax examples

Create Pull RequestBitbucket
initial

Create a pull-request into a given branch

Change assigneeJIRA1.1.0/2.1.0

Via this action it is possible to change the assignee to the issue 

Set priorityJIRA1.2.0/2.2.0Via this action it is possible to set the prioritization of the issue 
Set/Add fixed versionJIRA1.2.0/2.2.0Via this action is possible to set or add fixed versions to a issue 
Set/Add affected versionJIRA1.2.0/2.2.0Via this action is possible to set or add affected versions to a issue 
Set/Add componentsJIRA1.2.0/2.2.0Via this action is possible to set or add components to a issue
Set/Add labelsJIRA1.2.0/2.2.0Via this action is possible to set or add labels to a issue



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 Add the user1 and user2 to related and open pull-requests
Unapprove#keep/#unapprove
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 "-"


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

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


Different to Smart Commits in Fisheye

In general there is no large difference between the smart commits in Fisheye and Smart Commits in Bitbucket. The only difference is based on the difference between Git and e.g. Subversion. Git will handle the publishing of source code with the push mechanism, which will collect a set of commits in the local repository. Since there is no push, the commits are not visible to Bitbucket. So the actions which has been added to the commits, can not be parsed and executed. With a push the commits will be transferred to the Bitbucket repository and all change-sets, which has been pushed are now visible for Bitbucket. From then on it is possible to parse the changesets and execute the detected action. 

Another difference is, that the commits will not be parsed from the indexer. They will be parsed based on a post-receive hook. 



Configuration

The Smart Commit Plugin can be configured for in the settings area of the repository. 

Settings


SettingsDescription
Enable Smart CommitHere you can enable or disable the Smart Commits for a repository.
Enable Jira actionsThis option disables/enables the Jira actions of the plugin. This is needed, if the Bitbucket smart commits should be used together with the default Jira smart commit actions.
Enable Push ResponseThe result of the push will be printed as hook response
Issue-key regular expressionIf Jira uses non default issue keys, the regular expression to detect this issue keys can be set here.
Push response levelThe information level of the hook response
Approvals Strategy

Hey you can define which Approval strategy you would like to use. You can select the

  • Keep-Strategy: All approvals will be removed if no #keep keyword is available in each commit message.
  • Unapproved Strategy: Each approval will kept by default. A unapproval can be triggered with the keyword #unapprove
Maximal action logsThe number of log entries which should be displayed in the log tab.
Jira Comment HeaderUse your own comment header
Trigger action as default userUse not the credentials of the commit user to execute the smart commit actions. Use the credentials of the user, who will do the push.



The authentication method OAuth is needed together with the options "Allow 2-Legged OAuth" and "Allow user impersonation through 2-Legged OAuth" should be set. At least you have to set this option in JIRA for incoming connection and in Bitbucket for outgoing connections.


Logging

To analyze the behavior of the Smart Commit Plugin each action will be logged in a console. Log entries are categorized in Errors, Warnings or Information. 


  


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close