Gerrit Trigger

Skip to end of metadata
Go to start of metadata

This plugin integrates Jenkins to Gerrit code review for triggering builds when a "patch set" is created.

Plugin Information

Plugin ID gerrit-trigger Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies
2.11.1
Mar 21, 2014
1.480
credentials (version:1.6)
ssh-agent (version:1.3)
ssh-credentials (version:1.5.1)
rebuild (version:1.1, optional)
git-client (version:1.4.2, optional)
git (version:1.2.0, optional)
Source Code
Issue Tracking
Maintainer(s)
GitHub
Open Issues
Robert Sandell (id: rsandell)
Tomas Westling (id: twestling)
Usage Installations 2013-Apr 1439
2013-May 1485
2013-Jun 1584
2013-Jul 1698
2013-Aug 1784
2013-Sep 1795
2013-Oct 1872
2013-Nov 1899
2013-Dec 1984
2014-Jan 2078
2014-Feb 2197
2014-Mar 2353

Source Code

The source code is available on GitHub .

Set Up

Gerrit access rights

  1. Create the profile through in Gerrit web interface for your Jenkins user, and set up a SSH key for that user.
  2. Gerrit web interface > Admin > Groups > Non-Interactive Users > Add your jenkins user.
  3. Admin > Projects > ... > Access > Edit
    • Reference: refs/*
      • Read: ALLOW for Non-Interactive Users
    • Reference: refs/heads/*
      • Label Code-Review: -1, +1 for Non-Interactive Users
      • Label Verified: -1, +1 for Non-Interactive Users

Gerrit documentation: http://gerrit-documentation.googlecode.com/svn/Documentation/2.4.2/access-control.html#examples_cisystem

IMPORTANT: On Gerrit 2.7+, you also need to grant "Stream Events" capability. Without this, the plugin will not work, will try to connect to Gerrit repeatedly, and will eventually cause OutOfMemoryError on Gerrit.

  1. Gerrit web interface > People > Create New Group : "Event Streaming Users". Add your jenkins user.
  2. Admin > Projects > All-Projects > Access > Edit
    • Global Capabilities
      • Stream Events: ALLOW for Event Streaming Users

https://gerrit-documentation.googlecode.com/svn/Documentation/2.7/access-control.html#capability_streamEvents

Administrative Settings

Specify the Gerrit server settings via "Manage Jenkins > Gerrit Trigger"

Fill in the server settings:

Click "Test Connection" to verify the connection.

When everything seems ok, save your settings and restart the connection in the "Control" section at the bottom of the page:

There are many more settings for your pleasure, look at the individual help sections for information what they are about.

Trigger Configuration

In the "Build Triggers" section of your Job configuration page; tick "Gerrit event":

Specify what type of event(s) to trigger on:

  • Draft Published: Sent when a change moves from draft state to new. (only available in version 2.5 or higher of Gerrit).
  • Patchset Created: Sent when a new patchset arrives on a change. Before version 2.6.0, this was the only event you could trigger on.
  • Change Merged: Sent when a change is merged on the Gerrit server.
  • Comment Added: Sent when a comment is added to a change. Which category and value to trigger on can be configured. The available categories can be configured in the server settings for the plugin.
  • Ref Updated: Sent when a ref is updated on the Gerrit server, i.e. someone pushes past code review.

If you don't specify any event; Patchset Created and Draft Published (if available) will be selected by default.


Comment added configuration.

Specify what Gerrit project(s) to trigger a build on.

At least one project and branch pattern needs to be specified for a build to be triggered,and you can specify as many gerrit project to trigger on as you want.

Start by specifying the name of the Gerrit project in the left hand text field.
You can specify the name pattern in three different ways, as provided by the "Type" drop-down menu.

  • Plain: The exact name in Gerrit, case sensitive equality.

Then provide the name of the branch(es) to trigger on. The same "pattern types" is available as above.
So for example to trigger on all branches in the project you can specify:
  Type: Path
  Pattern: **
You can add more branch patterns by clicking on "Add Branch" and more projects by clicking "Add Project".

The same syntax works for specifying which file(s) to trigger on (this is only available in version 2.3 or higher of Gerrit).

Dynamic triggering

From version 2.6.0 of the plugin, a new way of configuring what projects, branches and files to trigger on is available.
 
By checking the checkbox "Dynamic Trigger Configuration", the user is asked for the URL to a file.

On a set interval, the plugin fetches and parses this file. The file contents should follow this syntax:

p=some/project
b^**/master/*
f~.*\.txt
p=some/other/project
b^**

Explanation:

p for project
b for branch
f for file
= for plain syntax
^ for ANT style syntax
~ for regexp syntax

Branch and file lines are assumed to be part of the closest preceding project line.

The dynamic triggering can be used in combination with the usual configuration, described above. The gerrit trigger will

trigger both for the dynamic and non-dynamic configurations.

The interval on which Jenkins fetches the file is configurable in the administrative pages for the Gerrit trigger, under advanced:

Use case

The reason for this functionality is that a user would want to update a list of what to trigger on outside of Jenkins.

Another use case is to run a build in Jenkins periodically that creates the list, then have several projects use the same list.

Gerrit hooks

Gerrit doesn't use the standard repository hooks.  To do an automatic update of jenkins on a patch you'll need to add a hook to the top-level gerrit hook directory ($site_path/hooks).

The equivalent of a git 'post-receive' hook for gerrit is a 'patchset-created' handler.  More info on gerrit hooks can be found here:

http://gerrit.googlecode.com/svn/documentation/2.1.2/config-hooks.html

Usage with the Git Plugin

To get the Git Plugin to download your change; set Refspec to $GERRIT_REFSPEC and the Choosing strategy to Gerrit Trigger. You may also need to set 'Branches to build' to $GERRIT_BRANCH. If this does not work for you set Refspec to refs/changes/*:refs/changes/* and 'Branches to build' to $GERRIT_REFSPEC.

Note: Be aware that $GERRIT_BRANCH and $GERRIT_REFSPEC are not set in the Ref Updated case. If you want to trigger a build, you can set Refspec and 'Branches to build' to $GERRIT_REFNAME.

Usage with Repo

If you are using a freestyle project and repo to download your code it would be as "easy" as.

repo init -u git://gerrit.mycompany.net/mymanifest.git
repo sync
repo download $GERRIT_PROJECT $GERRIT_CHANGE_NUMBER/$GERRIT_PATCHSET_NUMBER

Skip Vote

"Skipping" the vote means that if more than one build is triggered by a Gerrit event the outcome of this build that "skips its vote" won't be counted when the final vote is sent to Gerrit. If this is the only build that is triggered then the vote will be 0.

This can be useful if you have one job that triggers on all patch set created events that just checks that the commit message is correctly formatted, so it should only deny merging if it is a bad commit message but also not allow the merge just because the message was ok. In that scenario you could configure the "check commit message" job to skip voting on Successful.

Additional Screenshots

     

Tips & Tricks

This section contains some useful tips and tricks that users has come up with. Feel free to add your own.

Using "Build Now"

Normally when you have configured a job to be triggered by Gerrit you can't use the "Build Now" link anymore since your builds are dependent on information from Gerrit, especially if you are using the Git plugin to checkout your code in the workspace.

You can get around this limitation if you for example want to use the same job to build the master branch at some point. If you are using the Git plugin do the following

Add a String parameter called GERRIT_REFSPEC with the default value refs/heads/master

Using this trick will enable you to build, but no results will be sent to Gerrit since it is not triggered by it.

Multiple jobs review the same changeset (possibly giving different answers)

That's possible, see http://strongspace.com/rtyler/public/gerrit-jenkins-notes.pdf

Reduce number of notification emails

Since the trigger adds a comment in Gerrit for each build start and end, usually all the reviewers get a notification email. This can get quite annoying. However, it's possible to configure Gerrit so that only the change owner and people who starred the change get a notification email. To do this DENY the 'Email Reviewers' capability for the Gerrit user that is used by Jenkins. See https://gerrit-review.googlesource.com/Documentation/access-control.html#capability_emailReviewers.

Note to Gerrit 2.6 Users

The verdict category key values has changed in 2.6 from CDRV, VRIF to Code-Review and Verified. So in order to be able to trigger on comment added you need to change the settings on the "Manage Jenkins/Gerrit Trigger" page (it's hidden behind the advanced button) and reconfigure all your jobs so they can pick up the new values.

Also note that the Verified flag is no longer in Gerrit by default, see http://gerrit-documentation.googlecode.com/svn/Documentation/2.6/cmd-review.html so you'll need to add it to Gerrit for new installs.

The search page will also not show the verdigt of the patches until we've fixed that page, but it shouldn't hinder the functionality of that page.

Change Log

Version 2.11.1 (released Mar 21 2014)

Version 2.11.0 (released Jan 14 2014)

2.11.0-beta-4 promoted to "stable".

Version 2.11.0-beta-4 (released Dec 18 2013)

Last release for the year.

Fixes
  • JENKINS-21067 New server config not reachable if using a prefix in URL

Version 2.11.0-beta-3 (released Dec 16 2013)

Fixes
  • One more "Any Server" fix.
  • small jelly fix to make the trigger work like before with the templates plugin.

Version 2.11.0-beta-2 (released Dec 9 2013)

Fixes
  • URL encoding for project and branch when calling the REST Api
  • Updated the Gerrit documentation link on the query page to point to 2.8
  • Various fixes for using the "Any Server" trigger option.

Version 2.11.0-beta-2 (released Dec 9 2013)

Fixes
  • URL encoding for project and branch when calling the REST Api
  • Updated the Gerrit documentation link on the query page to point to 2.8
  • Various fixes for using the "Any Server" trigger option.

Version 2.11.0-beta-1 (released Nov 26 2013)

This version contains a lot of refactoring under the hood to make some of the features and future work possible.

Features
  • [JENKINS-17850] Multiple Gerrit server support
  • Option to use REST Api for submitting review
    • Allowing other plugins to provide line comments via extension point
  • Option to check changes from Gerrit and trigger missed patchsets.
  • The change's full commit message is available in triggered jobs, if Gerrit provides it.
  • New build parameter: GERRIT_TOPIC.
Fixes
  • Replaced deprecated `gerrit approve` with `gerrit review` as default command.
  • [JENKINS-10709] Multiple builds are triggered for one change in Gerrit.
  • Fixed an NPE in Watchdog causing the days not to show in the config UI
  • Git choosing strategy no longer uses FETCH_HEAD but the actual revision instead
  • [JENKINS-20098] When computing the changelog in the Git Plugin using GerritTriggerBuildChooser an UnsupportedOperationException is thrown

Version 2.10.1 (released June 17, 2013)

Fixes
  • Fixed NPE on "Query and Trigger Gerrit Patches". 
  • Connection to Gerrit is delayed during startup until all jobs are loaded.

Version 2.10.0 (released May 30, 2013)

Features and Fixes
  • Added Retrigger permission. 
    • Anyone with Build permission will also have Retrigger so you won't need to change the authorization config.
    • Gives you the ability to deny people to build a job but retrigger it if for example some environment issue broke the build.
  • Japanese translations for the things added in 2.9.0

Version 2.9.0 (released Mar 12, 2013)

Features and Fixes
  • Added a watchdog that can restart the Gerrit connection if nothing has happened for x minutes
  • Fixed so that a reconnect is attempted if connection gets broken before stream-events is fully initiated.
  • SOCS5 and HTTP proxy support for connecting to Gerrit
  • Added new parameters: 
    • GERRIT_EVENT_TYPE - states what type of event that triggered the build
    • GERRIT_CHANGE_ABANDONER_NAME, GERRIT_CHANGE_ABANDONER_EMAIL
    • GERRIT_CHANGE_RESTORER_NAME, GERRIT_CHANGE_RESTORER_EMAIL

Version 2.8.0 (released Feb 21, 2013)

Features and Fixes
  • Trigger on change-abandoned and change-restored events.
  • Configuration to turn off the compound email parameter - workaround for parameter issues on Windows.
  • URLConnection to the dynamic trigger config should now be properly closed.
  • Removed use of deprecated APIs in git-plugin's BuildChooser; follow up fix to JENKINS-16851, new dependency to git-plugin 1.2.0.

Version 2.7.0 (released Dec 5, 2012)

Features and Fixes
  • Custom messages from plugins takes into account all builds for an event
  • Custom messages from plugins moved from CUSTOM_MESSAGE into BUILD_STATS variable, added a checkbox to turn on/off plugin messages.
  • Ability to "skip voting" for a specific build result.
  • Fixed a circularity bug in Comment Added event, so Jenkins won't trigger on comments from itself.
  • Upgraded jsch to 0.1.49
  • Build current patchsets only is no longer experimental
  • More Japanese translations
  • Fixes and additions to help files
  • Added a timeout when fetching dynamic configuration files
  • Bumped Jenkins core dependency to 1.424
Dev related
  • GerritCause is now a sub class of SCMTriggerCause
  • Done some cleanups in the gerrit-event module
  • checkstyle:check is executed in the maven test phase, so the build will fail if you have checkstyle warnings.
  • ToGerritRunListener now has an ordinal of 10 003

Version 2.6.0 (released Sep 19, 2012)

Features and Fixes
  • Dynamic Gerrit triggering.
  • Triggering on comment-added, change-merged, ref-updated and draft-published now possible.
  • Refactorization of GerritTriggeredEvents and hashCode method implementation for events.
  • Fixed a double-triggering when a project is renamed.
  • New extension point for plugins to add custom messages to Gerrit at beginning/end of build.
  • JENKINS-11726
  • JENKINS-11582
  • JENKINS-10055

Version 2.5.2 (released May 7, 2012)

Features and Fixes
  • Corrected Gerrit version requirements for the "trigger on files" feature, it is now set to 2.3.
  • No quiet period when triggering builds manually (Retrigger and "Query and Trigger Gerrit Patches")
  • Fixed a deadlock when a job is saved at the same time as its being triggered.
  • More Japanese translations.

Version 2.5.1 (released Mar 13, 2012)

Features and Fixes
  • JENKINS-12836 Follow-up from previous version.

Version 2.5.0 (released Mar 8, 2012)

Features and Fixes
  • Gerrit version checking.
    • The plugin fetches the version of Gerrit each time the connection to Gerrit is started.
    • This will be used to filter out functionality that is not available in all Gerrit versions.
    • If a snapshot of Gerrit is used, all functionality will be enabled (as of today, only the file path triggering below uses the version check).
  • JENKINS-12836 Add a Descriptor for the Branch to avoid a warning in the logs.
  • Quiet Period. If a job has a configured quiet period; the trigger will use that if it is larger than the global configuration for the trigger.
  • File path triggering.
    • One or more file paths can now be entered in the config of a Jenkins project, in the same way as Gerrit project/branch.
    • The build will only trigger if the path is found in the patch set for this project/branch.
    • Useful for big gits with lots of smaller modules beneath it.
  • Custom message from workspace file.
    • A workspace file can now be updated with information that will be sent in the message from the trigger to Gerrit.

Version 2.4.0 (released Feb 17, 2012)

Features and Fixes
  • Custom URL per project. Each project can define what URL should be provided in the <BUILD_STATS> information that is sent to Gerrit.
  • JENKINS-11009 Silent Triggered builds now show up in the Manual Trigger monitor panel.
  • EXPERIMENTAL: Cancel old running jobs when a new Patch Set is uploaded on the same change.
    • This feature is set as experimental due to problems we've found during testing. 
    • You can enable the feature from the Manage Jenkins/Gerrit Trigger page.
    • All help in debugging the problems we've found is appreciated, that's why it is in this release. (The problems are described in the comment section on GitHub here).

Version 2.3.1 (released Sep 14, 2011)

Features and Fixes
  • Change owner and patch-set uploader as build parameters.
  • JENKINS-7067 Does not attempt to connect to Gerrit if there is no configuration (first start up)
  • Compatible with git plug-in >= 1.1.10
  • Reload from disk and other duplication related bug-fixes.

Version 2.3.0 (released Mar 31, 2011)

This is built against Jenkins 1.400 to have an easier release process, but it should still be binary compatible with Hudson 1.362+

Features and Fixes
  • JENKINS-7053 Escape quotes in build parameters
  • JENKINS-8578 Added permission-setting to perform "Query and Trigger Gerrit Patches"
  • JENKINS-8799 Administrator check for start/stop the Gerrit connection
  • Ant pattern matching on Windows
  • Allow custom build messages per job
  • JENKINS-7207 Teach the trigger to understand merge commits.

Version 2.2.0 (released Oct 7, 2010)

  New Features
  • Allow for searching and manual triggering of Gerrit Patches - the feature requires Gerrit version 2.1.4 or later, but can be disabled.
    • Known bug: when upgrading from previous release, the manual trigger page is disabled by default. Goto the Gerrit Management page and enable it under the advanced section.
  • Gerrit/GIT Project-name Autocompletion on trigger-config page.
  • Multiple build's results are reported on separate lines to Gerrit instead of "tab separated".
  • Approve commands are queued on a separate thread-pool instead of running on the last build's thread.

Version 2.1.0 (released July 26, 2010)

  New Features
  • JENKINS-6818 Retrigger builds. The users has the ability to retrigger a build. A new build with the same change info as the original build will be scheduled.
  Bugs fixed
  • JENKINS-6967 Missing default parameters.
  • JENKINS-6977 Images and help don't load when Hudson isn't running on the root URL.
  • Fixed some Leaking threads
  • Japanese translation

Version 2.0 (released July 5, 2010)

  • First release.

Labels

Edit
plugin-trigger plugin-trigger Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

Add Comment