Breadcrumbs

User Guide

Migrating from Smart Commits for Bitbucket Data Center?
Some features work differently in Bitbucket Cloud, and a few are not supported yet (e.g. time tracking with #time). See Differences to Data Center for details.

If your workspace also uses Jira's built-in Smart Commits, commands like #comment or transitions may be executed twice.


What is the Smart Commits for Bitbucket Cloud 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

Action

Application

Description

Comment

JIRA+Bitbucket

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 Jira comment will be the account of the Jira connection, the author of the Bitbucket comment will be the Smart Commits app. The date of the comment will be the date of the push action.

JIRA+Bitbucket

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. 

Add reviewer

Bitbucket

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)

Transition

JIRA

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 Request

Bitbucket

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

The pull request will be created by the Smart Commits app.

Change assignee

JIRA

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 priority

JIRA

During 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 version

JIRA

During the implementation of an issue, you made need to add or set the fixed version of the issue. The key #fixedVersion or #fixVersion allows you to add or set a version to the issue (e.g. #fixVersion+=1.0.0) 

Set/Add affected version

JIRA

During 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 components

JIRA

During 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 labels

JIRA

During 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 tasks

Bitbucket

During 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 effort

JIRA

When 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> ;

or

<ISSUE_KEY> <ACTION> <ACTION> <COMMAND_PARAMETERS> <ACTION> ;


Each Jira action segment must start with one or more valid issue keys, placed before any action keyword. Text before the first issue key, or after a ; and before the next issue key, is ignored for Jira actions. Bitbucket-only actions (e.g. #comment @stash, #pull, #reviewer, #task) do not need an issue key.


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


Example:

TEST-1 TEST-2 #remain 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 remaining 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 #remain 2d 5h ;
TEST-3 TEST-4 #remain 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

Action

Syntax

Example

Description

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

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

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=<display name or email>

#assignee=admin

Changes 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 message

Result

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

Multiple Issue actions 1 

TEST-1 #remain 1d;
TEST-2 #remain 2d;
TEST-3 #remain 3d;

  • Will set the remaining effort to 1 day for issue TEST-1

  • Will set the remaining effort to 2 days for issue TEST-2

  • Will set the remaining effort to 3 days for issue TEST-3

Multiple Issue actions 2 

TEST-1 #remain 1d #comment first comment;
TEST-2 #remain 2d #comment second comment;
TEST-3 #remain 3d #comment third comment;
 

  • Will set the remaining effort to 1 day for issue TEST-1 with the comment "first comment"

  • Will set the remaining effort to 2 days for issue TEST-2 with the comment "second comment"

  • Will set the remaining effort to 3 days for issue TEST-3 with the comment "third comment"

  • Will comment all relates pull request with the first 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
#remain 2d
; 
#comment @stash This is a Bitbucket comment only

  • Will produce a comment for issue TEST-1 and TEST2

  • Will set the remaining effort to 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

Add reviewer 

TEST-1 TEST-2 
#comment @jira The final changes are done
#remain 2d
;
#comment @stash Hey @user1 and @user2, please review my changes. Thx.
#reviewer @user1 @user2

  • Add a comment for issue TEST-1 and TEST2

  • Will set the remaining effort to 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 #remain 2h

  • Execute the transition "Start Progress" for the issue TEST-2

  • Will set the remaining effort to 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 #remain 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 set the remaining effort to 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 #remain 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 set the remaining effort to 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 #remain 1d

  • Add a comment to the issue TEST-2

  • Set the remaining time of the issue TEST-2 to 1 day


Configuration

The Smart Commits app can be configured in the app settings of the workspace, projects and/or repositories

Bildschirmfoto 2026-09-28 um 18.18.31.png


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.


Bildschirmfoto 2026-09-28 um 14.14.22.png


Jira advanced settings


Bildschirmfoto 2026-09-28 um 14.17.31.png


Settings

Description

Issue-key regular expression

The 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 Header

Enable 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, the commit hash $hash and the short commit hash $short-hash


Bitbucket Actions

Bildschirmfoto 2026-09-28 um 14.18.55.png


Jira Connection

All actions regarding Jira will be done via the Jira connections configured in the app settings, with the account of the connection.