its-base-based pluginsIn order to extract ITS ids from commit messages, its-phabricator uses [commentlink][upstream-comment-link-doc]s of ([per default][common-config-commentlink]) name “its-phabricator”.
The ([per default][common-config-commentlinkGroupIndex]) first group of commentlink.its-phabricator.match is considered the issue id.
So for example having
[commentlink "its-phabricator"]
match = [Bb][Uu][Gg][ ]*([1-9][0-9]*)
html = "<a href=\"http://my.issure.tracker.example.org/show_bug.cgi?id=$1\">(bug $1)</a>"
in etc/gerrit.config would allow to match the issues 4711, 167 from a commit message like
Sample commit message relating to bug 4711, and bug 167.
By setting a commentlink’s association on the plugin’s its-phabricator configuration, it is possible to require commits to carry ITS references; the following values are supported (default is OPTIONAL):
Example:
[plugin "its-phabricator"]
association = MANDATORY
in etc/gerrit.config would accept only commits that contain a valid issue id in the comment, matching the commentLink defined previously.
NOTE: Historically the association has been defined in the Gerrit’s commentLink section. That setting is deprecated but still supported for the current release. You are encouraged to move the association policy to the plugin section, the commentLink.association will be discontinued in the next major release.
The association can be overridden at project level in the project.config using the same syntax used in the gerrit.config. Project’s hierarchy will be respected when evaluating the links configuration and association policy.
It can be configured per project whether the issue tracker integration is enabled or not. To enable the issue tracker integration for a project the project must have the following entry in its project.config file in the refs/meta/config branch:
[plugin "its-phabricator"]
enabled = true
If plugin.its-phabricator.enabled is not specified in the project.config file the value is inherited from the parent project. If it is not set on any parent project the issue integration is disabled for this project.
By setting plugin.its-phabricator.enabled to true in the project.config of the All-Projects project the issue tracker integration can be enabled by default for all projects. During the initialization of the plugin you are asked if the issue 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.
With this it is possible to support integration with multiple issue tracker systems on a server. E.g. a project can choose if it wants to enable integration with Jira or with Bugzilla.
If child projects must not be allowed to disable the issue tracker system integration a project can enforce the issue tracker system integration for all child projects by setting plugin.its-phabricator.enabled to enforced.
The issue tracker system integration can be limited to specific branches by setting plugin.its-phabricator.branch. The branches may be configured using explicit ref names, ref patterns, or regular expressions. Multiple branches may be specified.
E.g. to limit the issue tracker system integration to the master branch and all stable branches the following could be configured:
[plugin "its-phabricator"]
enabled = true
branch = refs/heads/master
branch = ^refs/heads/stable-.*
To be able to make use of actions acting at the ITS project level, you must associate a Gerrit project to its ITS project counterpart.
It must be configured per project and per plugin. To configure the association for a project mapping to an ITS project named manhattan-project, the project must have the following entry in its project.config file in the refs/meta/config branch:
[plugin "its-phabricator"]
its-project = manhattan-project
Setting up which event in Gerrit (E.g.: “Change Merged”, or “User ‘John Doe’ voted ‘+2’ for ‘Code-Review’ on a change”) should trigger which action on the ITS (e.g.: “Set issue’s status to ‘Resolved’”) is configured through a rule base in etc/its/actions.config.
Although not a common setup the its-phabricator plugin supports connecting Gerrit to multiple issue tracking systems.
For example users may want to reference issues from two independent issue tracking systems (i.e. a Bugzilla and a Jira instance). In this configuration you can simply install both its plugins and configure them as described.
In situations where users want to reference issues from multiple instances of the same issue tracking system (e.g., two independent Bugzilla instances), create two its-bugzilla plugin files with different names (e.g., its-bugzilla-external.jar and its-bugzilla-internal.jar). Edit the file META-INF/MANIFEST.MF in the jar (extract using unzip), and change the name in the Gerrit-PluginName field to match the change to the filename. Now you just need to use the appropriate name to configure each plugin.
Example:
cd /tmp
wget 'https://gerrit-ci.gerritforge.com/job/plugin-its-bugzilla-bazel-master/lastSuccessfulBuild/artifact/bazel-bin/plugins/its-bugzilla/its-bugzilla.jar'
mkdir its-bugzilla-external
cd its-bugzilla-external
jar --verbose --extract --file ../its-bugzilla.jar
sed -i '' -e 's/its-bugzilla/its-bugzilla-external/' META-INF/MANIFEST.MF
jar --verbose --create --manifest=META-INF/MANIFEST.MF --file=../its-bugzilla-external.jar .
common-config-commentlink common-config-commentlinkGroupIndex
its-phabricator.commentlinkThis setting is useful to reuse the same comment link from different Its plugins. For example, if you set its-phabricator.commentlink to foo, then the comment link foo is used (instead of the comment link its-phabricator) to extract issue ids.
Default is its-phabricator
its-phabricator.commentlinkGroupIndexits-phabricator.commentlink that holds the issue id.
Default is 1, if there are are groups within the regular expression for the its-phabricator.commentlink comment link, and the default is 0, if there are no such groups.
its-phabricator.dummyIssuePatternThis setting is useful to bypass the MANDATORY check for commits matching a specific pattern.