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.
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.
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.
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.
|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.|
|If the changes are related to a pull-requests, it is possible to add reviewers to the pull-requests|
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.
This command transitions an issue to a particular workflow state. The smart commits will need to be fully qualified. See syntax examples
|Create Pull Request||Bitbucket|
Create a pull-request into a given branch
Via this action it is possible to change the assignee to the issue
|Set priority||JIRA||1.2.0/2.2.0||Via this action it is possible to set the prioritization of the issue|
|Set/Add fixed version||JIRA||1.2.0/2.2.0||Via this action is possible to set or add fixed versions to a issue|
|Set/Add affected version||JIRA||1.2.0/2.2.0||Via this action is possible to set or add affected versions to a issue|
|Set/Add components||JIRA||1.2.0/2.2.0||Via this action is possible to set or add components to a issue|
|Set/Add labels||JIRA||1.2.0/2.2.0||Via this action is possible to set or add labels to a issue|
Basic JIRA syntax
The basic syntax for JIRA commands is the following:
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.
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.
Also please note that commit actions can span more than one lines
Syntax of actions
#comment @jira @stash <text>
#comment This is my
first example comment
|Creates a comment to JIRA issues and Pull requests|
#comment @jira This is my
first example comment (only for Jira)
|Creates a comment to JIRA issues and *not* to Pull requests|
#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 comment||Creates 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
|Worklog + Comment|
#time <JIRA worlog syntax>
#comment This is my
second example comment
#time 4w 1d
#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|
|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=admin||Changes the assignee to the user admin|
|Set priority||#prio=<prioritization> ||#prio=Major |
Set prioritization "Major" to the issue TEST-1.
Blanks in the prioritization needs to be replaces with a minus "-"
Condition: Component must be available
|Set/Add affected version|
Condition: Version must be available
|Set/Add fixed version|
Condition: Version must be available
Comment and Worklog
Comment for JIRA and Bitbucket
Multiple Issue actions 1
Multiple Issue actions 2
Additional Bitbucket comment
Simple comment with unapprove
Simple comment with keep
JIRA action with keep
|Create Pull-Request|| |
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.
The Smart Commit Plugin can be configured for in the settings area of the repository.
|Enable Smart Commit||Here you can enable or disable the Smart Commits for a repository.|
|Enable Jira actions||This 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 Response||The result of the push will be printed as hook response|
|Issue-key regular expression||If Jira uses non default issue keys, the regular expression to detect this issue keys can be set here.|
|Push response level||The information level of the hook response|
Hey you can define which Approval strategy you would like to use. You can select the
|Maximal action logs||The number of log entries which should be displayed in the log tab.|
|Jira Comment Header||Use your own comment header|
|Trigger action as default user||Use 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.
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.