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
2.17.5 (archives)
Nov 30, 2015
rabbitmq-consumer (version:2.2, optional)
git-client (version:1.11.1, optional)
rebuild (version:1.25, optional)
git (version:2.3, optional)
Source Code
Issue Tracking
Pull Requests
Open Issues
Pull Requests
Robert Sandell (id: rsandell)
Tomas Westling (id: twestling)
Usage Installations 2014-Nov 2941
2014-Dec 2945
2015-Jan 3104
2015-Feb 3144
2015-Mar 3337
2015-Apr 3428
2015-May 3451
2015-Jun 3572
2015-Jul 3731
2015-Aug 3766
2015-Sep 3876
2015-Oct 3959

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:

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

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 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:

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://
repo sync

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:

  • The Playback Manager maintains a last known alive timestamp of events that were received by the Gerrit Server connection.
  • Upon re-connect, a request is made to the Gerrit Events-Log plugin installed on the Gerrit Server to determine which events may have been missed while the connection was down.
  • The events are then added to the Gerrit Trigger event queue to be processed.

Setup Requirements

The Playback Manager requires:

Setting up the REST api
  • To setup the REST api for the Gerrit Server Connection, navigate to Manage Jenkins > Gerrit Trigger and click on the Edit icon for the Server Connection.
  • Click on Advanced, and enter the Gerrit HTTP User and Gerrit HTTP Password values as shown below.

  • Click on Test REST Connection to verify the user and password settings.
  • Click on Save
  • Restart the connection using the Status icon in the Server Table shown below:

Gerrit Server Events-Log plugin
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

  • Once you have restarted the connection, click on the Edit icon in the Server Table. If there is a problem with the Playback Manager's configuration, you will see this:

  • If the Playback Manager is correctly setup, you will see the following in the Jenkins log file when the Gerrit Server Connection is started:
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


Workflow Jobs

Version 2.15.0 of the Gerrit Trigger plugin supports Jenkins Workflow job types. So as with the Freestyle job type, this plugin supports:

  1. Triggering of Workflow 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

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

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

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

Change Log

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)

  • Fix NPE involving null server CR/Ver labels (pull #257)

Version 2.17.1 (released Oct 28 2015)

Version 2.17.0 (released Oct 26 2015)

  • Update for upcoming change to Gerrit stream events in regards to updated attribute in Approval for responding to Comment Added events (pull #253)
  • JENKINS-30367,JENKINS-30393 Allow override of code-review/verified value from job (pull #255)
    This change also makes it so Jenkins doesn't send --verified at all for the review ssh command, if there is no value calculated, so if you change the defaults you shouldn't need to add the Verified label in Gerrit.

Version 2.16.0 (released Oct 02 2015)

Version 2.15.2 (released Sept 30 2015)

  • Fix to permit use of Forbidden files without File Paths (pull #251)

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)

  • Correct default values for Build Current Patchsets (pull #236)

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)

  • Another regression from JENKINS-23152. The correct event handling methods wasn't called for some event types causing weird loop-triggering behavior. (pull #204)

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

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

  • Enabled Base64EncodedString parameter to be used with Rebuild plugin (pull #199)
  • Regression from JENKINS-23152 fix; Running event threads as SYSTEM user (pull #200)

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

I Botched the beta-1 release.

Version 2.12.0 (released Nov 14 2014)

  • 2.12.0-beta-5 promoted to stable
  • Added Japanese translations (pull #190)

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)

  • Fixed disabled features not showing (pull #164)
  • JENKINS-24012 Fixed an issue with RabbitMQ (pull #166)
  • Added No connection on startup (pull #168)
  • Added selection for what labels to use for the REST API (pull #169)
  • Default "status:open" filled in on the search page (pull #163)
  • Added a trigger for comment added containing a specified RegEx (pull #170)

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
  • Added option to exclude drafts when triggering on patchset created event (pull #153)
  • Permit the setting of Build Schedule Delay to "0". Delay not needed with Replication Events (pull #143)
  • Bug: Copy REST API settings when creating new server (pull #156)
  • Bug: Password for SSH authentication file is now encrypted (pull #157)
  • JENKINS-23165 Don't send plain text password to browser (pull #158)
  • JENKINS-23421 Add custom parameter type for Base64 encoded value (pull #160)
  • Filter on change-kind in patchset-created REWORK, TRIVIAL_REBASE, NO_CODE_CHANGE (pull #159)
  • Removed delayed approval feature JENKINS-11409 (commit 48311)

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
  • Code refactoring to "break out" the gerrit-events module into its own separate project.
  • Added a "Forbidden Files" optional parameter to Gerrit Projects (commit 43372)
  • JENKINS-11409 Delayed approval mechanism (commit 5f672)
  • Add Pseudo Mode to server configuration (commit 0e735)
  • NPE Fix in the connection watchdog
  • Fixed log annotator when "Any Server" was used. (commit f8e50)
  • Moved "Server Control Panel" to main Management page
  • Feature to block build until Gerrit replication is completed. (commit ab429)
  • JENKINS-21547 Add information to console log
  • New functionality allowing one project's trigger to depend on others'. (commit 08fb5)
  • Various doc and help fixes
  • Add option for selecting non-encoded string for multiline text parameters. (commit cb285)

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.

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

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

  • 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)

  • 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)

  • 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.

  • [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.
  • 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)

  • 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

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.


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

Add Comment