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

{jenkins-plugin-info:pluginId=gerrit-trigger}

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

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

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:

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.

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:

Note1: anonymous user must have READ permissions to Jobs in order for this feature to work.

Note2: a specific Gerrit server must be selected selecting "any server" will not trigger jobs.

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. This may be under ''Additional Behaviours/Strategy For Choosing What To Build' rather than directly visible as depicted in the screenshot. 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

Missed Events Playback Feature (Available from v. 2.14.0)

This feature replaces the "Check Non-Reviewed Patchsets" option that was part of a Job's Gerrit Trigger configuration.

If your Jenkins instance has been down for a period of time (upgrade or maintenance), the Missed Events Playback Feature ensures that any missed events are re-played and builds are triggered.

The mechanics are as follows:

Setup Requirements

The Playback Manager requires:

Setting up the REST api

Gerrit Server Events-Log plugin

Please note that if the Gerrit Server Events-Log plugin is not installed on the Gerrit Server, then the Playback Manager will be disabled.

Verifying functionality

INFO: (8) missed events to process for server: defaultServer ...

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

     

Pipeline Jobs

Version 2.15.0 of the Gerrit Trigger plugin supports Jenkins Pipeline job types. So as with the traditional job types, this plugin supports:

  1. Triggering of Pipeline Jobs based on Gerrit Event notifications e.g. the Patchset Created event.
  2. Checkout of the change-set revision from the Gerrit Git repository. See example below.
  3. Sending of the "build completed" command to Gerrit (with Verified label etc).

The plugin doesn't currently offer a dedicated DSL syntax for performing the change-set checkout. However, it's very easy to perform the checkout using the Gerrit parameters provided to the build, along with the existing Workflow step for Git (or other supported SCM) e.g.

node {
  // Checkout the Gerrit git repository using the existing
  // workflow git step...
  git url: '<gerrit-git-repo-url>'

  // Fetch the changeset to a local branch using the build parameters provided to the
  // build by the Gerrit plugin...
  def changeBranch = "change-${GERRIT_CHANGE_NUMBER}-${GERRIT_PATCHSET_NUMBER}"
  sh "git fetch origin ${GERRIT_REFSPEC}:${changeBranch}"
  sh "git checkout ${changeBranch}"

  // Build the changeset rev source etc...
}

Note though that with this approach the changelog will not show correctly.

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.  This can easily be added back to all projects.  Otherwise the Gerrit Trigger will fail to submit votes for jobs, due to the invalid label.

Alternately, you can remove the verified flag from the command used to submit votes for changes, and simply have the trigger submit code review votes:

  1. Go to "Manage Jenkins" and click the "Gerrit Trigger" link
  2. Under "Gerrit Servers" next to your server(s) click the "Edit" button (looks like a gear, other icons may overlap it)
  3. Under "Gerrit Reporting Values" click the Advanced button at the bottom
  4. Under "Gerrit Verified Commands" remove the '--verified <VERIFIED>' sections from each command, see screenshot

As of version 2.17.0 the verified "vote" is not sent at all to Gerrit (removed from the command line/rest call) unless there is an actual value to be sent. So if you change the configuration to contain only values for code review and empty strings for verified you won't get the error.

Change Log

Version 2.29.0 (released Feb 15 2019)

Version 2.28.0 (released Dec 19 2018)

Version 2.27.7 (released Sep 3 2018)

Version 2.27.6 (released Aug 24 2018)

Version 2.27.5 (released Feb 26 2018)

Version 2.27.4 (released Feb 20 2018)

Version 2.27.3 (released Jan 26 2018)

Version 2.27.2 (released Jan 15 2018)

Version 2.27.1 (released Dec 06 2017)

Version 2.27.0 (released Dec 01 2017)

Version 2.26.2 (released Oct 30 2017)

Version 2.26.1 (released Oct 12 2017)

Version 2.26.0 (released Sep 13 2017)

Version 2.25.0 (released Aug 11 2017)

Version 2.24.0 (released Jul 3 2017)

Version 2.23.3 (released Jun 9 2017)

Version 2.23.2 (released Apr 19 2017)

Version 2.23.1 (released Apr 11 2017)

Version 2.23.0 (released Nov 25 2016)

Version 2.22.0 (released Aug 17 2016)

This version does not contain the changes in 2.22.0-beta-1, they will be incorporated at a later date

Version 2.22.0-beta-1 (released Jul 06 2016)

Version 2.21.1 (released Jun 07 2016)

Version 2.21.0 (released May 30 2016)

Version 2.20.0 (released Apr 12 2016)

Version 2.19.0 (released Mar 31 2016)

Version 2.18.4 (released Mar 09 2016)

Version 2.18.3 (released Jan 05 2016)

Version 2.18.2 (released Dec 11 2015)

Version 2.18.1 (released Dec 3 2015)

Version 2.18.0 (released Dec 1 2015)

Version 2.17.5 (released Nov 30 2015)

Version 2.17.4 (released Nov 27 2015)

Version 2.17.3 (released Nov 26 2015)

Version 2.17.2 (released Oct 29 2015)

Version 2.17.1 (released Oct 28 2015)

Version 2.17.0 (released Oct 26 2015)

Version 2.16.0 (released Oct 02 2015)

Version 2.15.2 (released Sept 30 2015)

Version 2.15.1 (released Sept 14 2015)

Version 2.15.0 (released Aug 31 2015)

2.15.0-beta-1 promoted to stable

Version 2.15.0-beta-1 (released Aug 17 2015)

Version 2.14.0 (released Jun 05 2015)

2.14.0-beta-3 promoted to stable

Version 2.14.0-beta-3 (released May 27 2015)

Version 2.14.0-beta-2 (released May 26 2015)

Version 2.14.0-beta-1 (released May 20 2015)

Version 2.13.0 (released Apr 24 2015)

2.13.0-beta-6 promoted to stable.

Version 2.13.0-beta-6 (released Apr 7 2015)

Version 2.13.0-beta-5 (released Feb 23 2015)

Version 2.13.0-beta-4 (released Feb 16 2015)

Version 2.13.0-beta-3 (released Feb 6 2015)

Version 2.13.0-beta-2 (released Jan 15 2015)

I Botched the beta-1 release.

Version 2.12.0 (released Nov 14 2014)

Version 2.12.0-beta-5 (released Oct 30 2014)

Final rc for 2.12

Version 2.12.0-beta-4 (released Aug 28 2014)

Version 2.12.0-beta-3 (released Jun 30 2014)

Still calling it beta since I haven't had time o test it in a staging environment yet.

Features and Fixes

Version 2.12.0-beta-2 (released Apr 28 2014)

Features and Fixes

Version 2.12.0-beta-1 (released Apr 28 2014)

Bumped core dependency to 1.509.3

Features and Fixes

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

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

Fixes

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

Fixes

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

Fixes

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
Fixes

Version 2.10.1 (released June 17, 2013)

Fixes

Version 2.10.0 (released May 30, 2013)

Features and Fixes

Version 2.9.0 (released Mar 12, 2013)

Features and Fixes

Version 2.8.0 (released Feb 21, 2013)

Features and Fixes

Version 2.7.0 (released Dec 5, 2012)

Features and Fixes
Dev related

Version 2.6.0 (released Sep 19, 2012)

Features and Fixes

Version 2.5.2 (released May 7, 2012)

Features and Fixes

Version 2.5.1 (released Mar 13, 2012)

Features and Fixes

Version 2.5.0 (released Mar 8, 2012)

Features and Fixes

Version 2.4.0 (released Feb 17, 2012)

Features and Fixes

Version 2.3.1 (released Sep 14, 2011)

Features and 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

Version 2.2.0 (released Oct 7, 2010)

  New Features

Version 2.1.0 (released July 26, 2010)

  New Features
  Bugs fixed

Version 2.0 (released July 5, 2010)