This plugin allows to associate IBM Rational Team Concert (RTC) issues to Git commits / Gerrit Changes using the Gerrit ChangeListener and CommitValidator interfaces.
Main integration points provided are:
It can be configured per project whether the RTC integration is enabled or not. To enable the RTC integration for a project the project must have the following entry in its project.config file in the refs/meta/config branch:
[plugin "its-rtc"]
enabled = true
If plugin.its-rtc.enabled is not specified in the project.config file the value is inherited from the parent project. If it is also not set on any parent project the RTC integration is disabled for this project.
By setting plugin.its-rtc.enabled to true in the project.config of the All-Projects project the RTC integration can be enabled by default for all projects. During the initialization of the plugin you are asked if the RTC integration should be enabled by default for all projects and if yes this setting in the project.config of the All-Projects project is done automatically.
If child projects must not be allowed to disable the RTC integration a project can enforce the RTC integration for all child projects by setting plugin.its-rtc.enabled to enforced.
On the project info screen there is a dropdown list for the plugin.its-rtc.enabled parameter which offers the values true, false, enforced and INHERIT. Project owners can change this parameter and save it. If the RTC integration is enforced by a parent project the dropdown list is disabled.
The RTC integration can be limited to specific branches by setting plugin.its-rtc.branch. The branches may be configured using explicit branch names, ref patterns, or regular expressions. Multiple branches may be specified.
E.g. to limit the RTC integration to the master branch and all stable branches the following could be configured:
[plugin "its-rtc"]
enabled = true
branch = refs/heads/master
branch = ^refs/heads/stable-.*
Git commits are associated to RTC issues reusing the existing Gerrit commitLink configuration to extract the issue ID from commit comments.
Additionally you need to specify the enforcement policy for git commits with regards to issue-tracker associations; the following values are supported:
MANDATORY : One or more issue-ids are required in the git commit message, otherwise the git push will be rejected. NOTE: triggers a synchronous API call to RTC for the issue-id lookup, push is blocked until the operation is completed.
SUGGESTED : Whenever git commit message does not contain one or more issue-ids, a warning message is displayed as a suggestion on the client. NOTE: triggers a synchronous API call to RTC for the issue-id lookup, push is blocked until the operation is completed.
OPTIONAL : Issues-ids are liked when found on git commit message, no warning are displayed otherwise.
Example:
[commentLink "its-rtc"] match = RTC#([0-9]*) html = "<a href=\"https://rtc.gerritforge.com:9443/ccm/browse/$1\">$1</a>" association = OPTIONAL
Once a Git commit with a comment link is detected, the RTC issue ID is extracted and a new comment added to the issue, pointing back to the original Git commit.
In order for Gerrit to connect to RTC REST-API, url and credentials are required in your gerrit.config / secure.config under the [its-rtc] section.
Example:
[its-rtc] url=https://rtc.gerritforge.com:9443/ccm username=rtcuser passsword=rtcpass
RTC credentials and connectivity details are asked and verified during the Gerrit init.
There are no additional settings required for a default connectivity from Gerrit to RTC and the default JVM settings are automatically taken for opening outbound connections.
However connectivity to RTC could be highly customised for defining the protocol security level, pooling and network settings. This allows the administrator to have full control of the output pipe to RTC and the propagation of the Change events to the associated issues in a high-loaded production environment.
All settings are defined in gerrit.config under the same [its-rtc] section. See below the list of the most important parameters and their associated meaning.
sslVerify : [TRUE|FALSE]. When using HTTP/S to connect to RTC (the most typical scenario) allows to enforce (recommended) or disable (ONLY FOR TEST ENVIRONMENTS) the X.509 Certificates validation during SSL handshake. If unsure say TRUE.
httpSocketTimeout : <number> Defines the socket timeout in milliseconds, which is the timeout for waiting for data or, put differently, a maximum period inactivity between two consecutive data packets). A timeout value of zero is interpreted as an infinite timeout.
httpSocketBufferSize : <number> Determines the size of the internal socket buffer used to buffer data while receiving / transmitting HTTP messages.
httpSocketReuseaddr : [TRUE|FALSE] Defines whether the socket can be bound even though a previous connection is still in a timeout state.
httpConnectionTimeout : <number> Determines the timeout in milliseconds until a connection is established. A timeout value of zero is interpreted as an infinite timeout.
httpConnectionStalecheck : [TRUE|FALSE] Determines whether stale connection check is to be used. The stale connection check can cause up to 30 millisecond overhead per request and should be used only when appropriate. For performance critical operations this check should be disabled.
httpSocketKeepalive : [TRUE|FALSE] Defines whether or not TCP is to send automatically a keepalive probe to the peer after an interval of inactivity (no data exchanged in either direction) between this host and the peer. The purpose of this option is to detect if the peer host crashes.
httpConnManagerTimeout : <number> Defines the timeout in milliseconds used when retrieving a free connection from the pool of outbound HTTP connections allocated.
httpConnManagerMaxTotal : <number> Defines the maximum number of outbound HTTP connections in total. This limit is interpreted by client connection managers and applies to individual manager instances.
NOTE: The full list of all available HTTP network connectivity parameters can be found under the Apache Commons HTTP Client 4.2.x documentation. Gerrit parameters names are the CamelCase version of the string values of the Apache HTTP Client ones.
RTC plugin is integrated as a Gerrit init step in order to simplify and guide through the configuration of RTC integration and connectivity check, avoiding bogus settings to prevent Gerrit plugin to start correctly.
Gerrit init example:
*** IBM Rational Team Concert Integration
***
Issue tracker integration for all projects? [DISABLED/?]: enabled
Branches for which the issue tracker integration should be enabled (ref, ref pattern or regular expression) [refs/heads/*]:
*** IBM Rational Team Concert connectivity
***
RTC CCM URL (empty to skip) : https://rtc.gerritforge.com:9443/ccm
RTC username []: gerrit
Change luca's password [y/N]? y
luca's password : ******
confirm password : ******
Verify SSL Certificates [TRUE/?]: false
Test connectivity to https://rtc.gerritforge.com:9443/ccm [y/N]: y
Checking IBM Rational Team Concert connectivity ... [OK]
*** Rational Team Concert issue-tracking association
***
RTC issue-Id regex [RTC#([0-9]+)]:
RTC-Id enforced in commit message [OPTIONAL/?]: suggested
RTC plugin is able to automate status transition on the issues based on code-review actions performed on Gerrit; actions are performed on RTC using the username/password provided during Gerrit init. Transition automation is driven by $GERRIT_SITE/issue-state-transition.config file.
Syntax of the status transition configuration file is the following:
[action "<issue-status-action>"] change=<change-action> verified=<verified-value> code-review=<code-review-value>
<issue-status-action> : Action to perform on RTC issue when all the condition in the stanza are met.
<change-action> : Action performed on Gerrit change-id, possible values are: created, commented, merged, abandoned, restored
<verified-value> : Verified flag added on Gerrit with values from -1 to +1
<code-review-value> : Code-Review flag added on Gerrit with values from -2 to +2
Note: multiple conditions in the action stanza are optional but at least one must be present.
Example:
[action "Start Progress"] change=created [action "Resolve Issue"] verified=+1 code-review=+2 [action "Close Issue"] change=merged [action "Stop Progress"] change=abandoned
The above example defines four status transition on RTC, based on the following conditions: