02/24/2016
in Technology
Automated Issue Documentation with JIRA© and SCM-Manager
Table of Contents
+++This post was migrated from our former blog about SCM-Manager Universe. Therefore, it is only available in English. Enjoy reading.+++
SCM-Manager can be connected to several issue tracking applications like Bugzilla, Redmine or JIRA©. The basic functionality of those plugins is all the same: They enable you to change the status and add comments to issues. Beyond that the scm-jira-plugin offers several additional options which we want to explain.
Automation with the JIRA Plugin for SCM-Manager
You can install the JIRA© plugin like any other SCM-Manager plugin. Go to the Config → Plugins screen and hit the install button for the scm-jira-plugin. Then you’ll have to restart the application. After that the plugin is ready for configuration. The current version of the plugin is 1.19.
Plugin Configuration
The JIRA© plugin can be configured in 2 different ways: Generally or per repository. You can use a combination of both configurations or disable the repository configuration. Both configurations require the same information.
The general configuration is valid for all repositories. You can access it via the Config → General screen.
The repository configuration is useful if you use different workflows or different JIRA© servers for your projects/repositories. The repository configuration allows you to configure a different prefix or status modification words for each repository. The configuration will be activated as soon as an URL is specified. You can find the configuration in the info section of the repositories.
Field Annotations
Url: The URL specifies the location of the JIRA© instance that SCM-Manager is supposed to communicate with (e.g. https://yourDomain/jira). The URL needs to be a fully qualified domain name or IP-address.
Do not allow repository configuration: Set this option to true to disable the configuration of single repositories and to force the usage of the general configurations for each repository. This option is only available at the general configuration.
Update Jira Issues: Activate this checkbox to true to enable SCM-Manager to add comments to specified JIRA© issues.
Enable Status Modification: Enable this checkbox to allow SCM-Manager to modify the status of specified JIRA© issues.
Status Modification Words: If the status modification is enabled you can add keywords that can be used for state transitions. Let’s say you have configured this workflow in JIRA©:
You can add the names of the state transitions (e.g. start progress, stop progress, done). Then you have to use exactly these terms in commit messages to modify the status of an issue.
You can also use a mapping for the state transitions (e.g. start = start progress, fix = done, solved = done, …). This way you can configure several different words to use the status modification feature.
Role visibility (optional): Allows you to restrict the visibility of the automatically generated comments in JIRA©.
Comment prefix (optional): Use this field to configure a prefix that will be used at the beginning of each comment that is added by SCM-Manager. This allows you to easily distinguish automatically generated from manual comments in JIRA©.
Username and Password (optional): If you use different usernames and passwords for JIRA© and SCM-Manager you have to configure a default user here. This user will be used to update the JIRA© issues. If you don’t configure this default user, JIRA© and SCM-Manager have to use the same usernames and passwords, because the plugin uses the user credentials that were used for the push for the JIRA© authentication.
Enable resubmission: You can use this option to store commits in case the JIRA© server isn’t available. Stored commits will be resubmitted when you use the “Resubmit stored comments” option.
Rest API v2: Set this option to true if you use JIRA© 7 or later, because API v1 was dropped with JIRA© 7.
E-Mail (optional): Add an E-Mail address here if you want to be notified in case updating of a JIRA© issue fails.
Resubmit stored comments: Use this button to resubmit stored commits if you have activated the “Enable resubmission” option. If you have configured a default user in the fields above that user will be used for the resubmission. If you haven’t, the current user will be used. So you have to ensure that the user has the required permissions in JIRA© to submit the comments and to change the status of issues.
Usage of the JIRA© Plugin
After the configuration is done, the JIRA© plugin is ready to use. You only need to use the issue-IDs in your commit messages to use the update feature. If you want to use the status modification feature you simply have to use the status modification words in commit messages.
“SCM-20” is the issue-ID and “fixed” is one of the configured status modification words. It doesn’t matter in which order or where you use issue-IDs and status modification words, SCM-Manager screens the whole commit message for the corresponding strings. In the commit history in SCM-Manager you can see identified issue-IDs and you can jump to them in JIRA©.
Hint: It is advisable to select status modification words wisely. They shouldn’t be too common, because you don’t want to modify issues accidentally.
In JIRA© you can identify comments that were made by SCM-Manager by the comment prefix, we used “[SCM]”.
You can also mention multiple issue-IDs in one commit message. The only thing that isn’t possible, is to use different status modification words in one commit. If you use a status modification word it will be applied for all issue-IDs that are mentioned in the commit message.
Integration of SCM-Manager with JIRA© for Automation
The JIRA© plugin allows you to integrate SCM-Manager with JIRA© and offers a broad functionality. It allows you to modify the status of issues and to add comments and even if your JIRA© server is unavailable for some time, you can resubmit your commits.
