zuul/doc/source/zuul.rst

title

Zuul

Zuul

Configuration

Zuul has three configuration files:

zuul.conf

Connection information for Gerrit and Gearman, locations of the other config files.

layout.yaml

Project and pipeline configuration -- what Zuul does.

logging.conf

Python logging config.

Examples of each of the three files can be found in the etc/ directory of the source distribution.

zuul.conf

Zuul will look for /etc/zuul/zuul.conf or ~/zuul.conf to bootstrap its configuration. Alternately, you may specify -c /path/to/zuul.conf on the command line.

Gerrit and Gearman connection information are each described in a section of zuul.conf. The location of the other two configuration files (as well as the location of the PID file when running Zuul as a server) are specified in a third section.

The three sections of this config and their options are documented below. You can also find an example zuul.conf file in the git repository

gearman

server

Hostname or IP address of the Gearman server. server=gearman.example.com

port

Port on which the Gearman server is listening. port=4730

gearman_server

start

Whether to start the internal Gearman server (default: False). start=true

log_config

Path to log config file for internal Gearman server. log_config=/etc/zuul/gearman-logging.yaml

gerrit

server

FQDN of Gerrit server. server=review.example.com

baseurl

Optional: path to Gerrit web interface. Defaults to https://<value of server>/. baseurl=https://review.example.com/review_site/

user

User name to use when logging into above server via ssh. user=zuul

sshkey

Path to SSH key to use when logging into above server. sshkey=/home/zuul/.ssh/id_rsa

zuul

layout_config

Path to layout config file. Used by zuul-server only. layout_config=/etc/zuul/layout.yaml

log_config

Path to log config file. Used by zuul-server only. log_config=/etc/zuul/logging.yaml

pidfile

Path to PID lock file. Used by zuul-server only. pidfile=/var/run/zuul/zuul.pid

state_dir

Path to directory that Zuul should save state to. Used by all Zuul commands. state_dir=/var/lib/zuul

report_times

Boolean value (true or false) that determines if Zuul should include elapsed times for each job in the textual report. Used by zuul-server only. report_times=true

status_url

URL that will be posted in Zuul comments made to Gerrit changes when starting jobs for a change. Used by zuul-server only. status_url=https://zuul.example.com/status

url_pattern

If you are storing build logs external to the system that originally ran jobs and wish to link to those logs when Zuul makes comments on Gerrit changes for completed jobs this setting configures what the URLs for those links should be. Used by zuul-server only. http://logs.example.com/{change.number}/{change.patchset}/{pipeline.name}/{job.name}/{build.number}

job_name_in_report

Boolean value (true or false) that indicates whether the job name should be included in the report (normally only the URL is included). Defaults to false. Used by zuul-server only. job_name_in_report=true

merger

git_dir

Directory that Zuul should clone local git repositories to. git_dir=/var/lib/zuul/git

git_user_email

Optional: Value to pass to git config user.email. git_user_email=zuul@example.com

git_user_name

Optional: Value to pass to git config user.name. git_user_name=zuul

zuul_url

URL of this merger's git repos, accessible to test workers. Usually "http://zuul.example.com/p" or "http://zuul-merger01.example.com/p" depending on whether the merger is co-located with the Zuul server.

log_config

Path to log config file for the merger process. log_config=/etc/zuul/logging.yaml

pidfile

Path to PID lock file for the merger process. pidfile=/var/run/zuul-merger/merger.pid

smtp

server

SMTP server hostname or address to use. server=localhost

default_from

Who the email should appear to be sent from when emailing the report. This can be overridden by individual pipelines. default_from=zuul@example.com

default_to

Who the report should be emailed to by default. This can be overridden by individual pipelines. default_to=you@example.com

layout.yaml

This is the main configuration file for Zuul, where all of the pipelines and projects are defined, what tests should be run, and what actions Zuul should perform. There are three sections: pipelines, jobs, and projects.

Includes

Custom functions to be used in Zuul's configuration may be provided using the includes directive. It accepts a list of files to include, and currently supports one type of inclusion, a python file:

includes:
  - python-file: local_functions.py

python-file

The path to a python file. The file will be loaded and objects that it defines will be placed in a special environment which can be referenced in the Zuul configuration. Currently only the parameter-function attribute of a Job uses this feature.

Pipelines

Zuul can have any number of independent pipelines. Whenever a matching Gerrit event is found for a pipeline, that event is added to the pipeline, and the jobs specified for that pipeline are run. When all jobs specified for the pipeline that were triggered by an event are completed, Zuul reports back to Gerrit the results.

There are no pre-defined pipelines in Zuul, rather you can define whatever pipelines you need in the layout file. This is a very flexible system that can accommodate many kinds of workflows.

Here is a quick example of a pipeline definition followed by an explanation of each of the parameters:

- name: check
  manager: IndependentPipelineManager
  trigger:
    gerrit:
      - event: patchset-created
  success:
    verified: 1
  failure:
    verified: -1

name

This is used later in the project definition to indicate what jobs should be run for events in the pipeline.

description

This is an optional field that may be used to provide a textual description of the pipeline.

success-message

An optional field that supplies the introductory text in message reported back to Gerrit when all the voting builds are successful. Defaults to "Build successful."

failure-message

An optional field that supplies the introductory text in message reported back to Gerrit when at least one voting build fails. Defaults to "Build failed."

footer-message

An optional field to supply additional information after test results. Useful for adding information about the CI system such as debugging and contact details.

manager

There are currently two schemes for managing pipelines:

IndependentPipelineManager

Every event in this pipeline should be treated as independent of other events in the pipeline. This is appropriate when the order of events in the pipeline doesn't matter because the results of the actions this pipeline performs can not affect other events in the pipeline. For example, when a change is first uploaded for review, you may want to run tests on that change to provide early feedback to reviewers. At the end of the tests, the change is not going to be merged, so it is safe to run these tests in parallel without regard to any other changes in the pipeline. They are independent.

Another type of pipeline that is independent is a post-merge pipeline. In that case, the changes have already merged, so the results can not affect any other events in the pipeline.

DependentPipelineManager

The dependent pipeline manager is designed for gating. It ensures that every change is tested exactly as it is going to be merged into the repository. An ideal gating system would test one change at a time, applied to the tip of the repository, and only if that change passed tests would it be merged. Then the next change in line would be tested the same way. In order to achieve parallel testing of changes, the dependent pipeline manager performs speculative execution on changes. It orders changes based on their entry into the pipeline. It begins testing all changes in parallel, assuming that each change ahead in the pipeline will pass its tests. If they all succeed, all the changes can be tested and merged in parallel. If a change near the front of the pipeline fails its tests, each change behind it ignores whatever tests have been completed and are tested again without the change in front. This way gate tests may run in parallel but still be tested correctly, exactly as they will appear in the repository when merged.

One important characteristic of the DependentPipelineManager is that it analyzes the jobs that are triggered by different projects, and if those projects have jobs in common, it treats those projects as related, and they share a single virtual queue of changes. Thus, if there is a job that performs integration testing on two projects, those two projects will automatically share a virtual change queue. If a third project does not invoke that job, it will be part of a separate virtual change queue, and changes to it will not depend on changes to the first two jobs.

For more detail on the theory and operation of Zuul's DependentPipelineManager, see: gating.

trigger

Exactly one trigger source must be supplied for each pipeline. Triggers are not exclusive -- matching events may be placed in multiple pipelines, and they will behave independently in each of the pipelines they match. You may select from the following:

gerrit

This describes what Gerrit events should be placed in the pipeline. Multiple gerrit triggers may be listed. Further parameters describe the kind of events that match:

event The event name from gerrit. Examples: patchset-created, comment-added, ref-updated. This field is treated as a regular expression.

branch The branch associated with the event. Example: master. This field is treated as a regular expression, and multiple branches may be listed.

ref On ref-updated events, the branch parameter is not used, instead the ref is provided. Currently Gerrit has the somewhat idiosyncratic behavior of specifying bare refs for branch names (e.g., master), but full ref names for other kinds of refs (e.g., refs/tags/foo). Zuul matches what you put here exactly against what Gerrit provides. This field is treated as a regular expression, and multiple refs may be listed.

approval This is only used for comment-added events. It only matches if the event has a matching approval associated with it. Example: code-review: 2 matches a +2 vote on the code review category. Multiple approvals may be listed.

email_filter This is used for any event. It takes a regex applied on the performer email, i.e. Gerrit account email address. If you want to specify several email filters, you must use a YAML list. Make sure to use non greedy matchers and to escapes dots! Example: email_filter: ^.*?@example\.org$.

username_filter This is used for any event. It takes a regex applied on the performer username, i.e. Gerrit account name. If you want to specify several username filters, you must use a YAML list. Make sure to use non greedy matchers and to escapes dots! Example: username_filter: ^jenkins$.

comment_filter This is only used for comment-added events. It accepts a list of regexes that are searched for in the comment string. If any of these regexes matches a portion of the comment string the trigger is matched. comment_filter: retrigger will match when comments containing 'retrigger' somewhere in the comment text are added to a change.

require-approval This may be used for any event. It requires that a certain kind of approval be present for the current patchset of the change (the approval could be added by the event in question). It takes several sub-parameters, all of which are optional and are combined together so that there must be an approval matching all specified requirements.

username If present, an approval from this username is required.

email-filter If present, an approval with this email address is required. It is treated as a regular expression as above.

older-than If present, the approval must be older than this amount of time to match. Provide a time interval as a number with a suffix of "w" (weeks), "d" (days), "h" (hours), "m" (minutes), "s" (seconds). Example 48h or 2d.

newer-than If present, the approval must be newer than this amount of time to match. Same format as "older-than".

Any other field is interpreted as a review category and value pair. For example verified: 1 would require that the approval be for a +1 vote in the "Verified" column.

timer

This trigger will run based on a cron-style time specification. It will enqueue an event into its pipeline for every project defined in the configuration. Any job associated with the pipeline will run in response to that event.

time The time specification in cron syntax. Only the 5 part syntax is supported, not the symbolic names. Example: 0 0 * * * runs at midnight.

dequeue-on-new-patchset

Normally, if a new patchset is uploaded to a change that is in a pipeline, the existing entry in the pipeline will be removed (with jobs canceled and any dependent changes that can no longer merge as well. To suppress this behavior (and allow jobs to continue running), set this to false. Default: true.

success

Describes where Zuul should report to if all the jobs complete successfully. This section is optional; if it is omitted, Zuul will run jobs and do nothing on success; it will not even report a message to Gerrit. If the section is present, the listed reporter plugins will be asked to report on the jobs. Each reporter's value dictionary is handled by the reporter. See reporters for more details.

failure

Uses the same syntax as success, but describes what Zuul should do if at least one job fails.

start

Uses the same syntax as success, but describes what Zuul should do when a change is added to the pipeline manager. This can be used, for example, to reset the value of the Verified review category.

precedence

Indicates how the build scheduler should prioritize jobs for different pipelines. Each pipeline may have one precedence, jobs for pipelines with a higher precedence will be run before ones with lower. The value should be one of high, normal, or low. Default: normal.

window

DependentPipelineManagers only. Zuul can rate limit DependentPipelineManagers in a manner similar to TCP flow control. Jobs are only started for changes in the queue if they sit in the actionable window for the pipeline. The initial length of this window is configurable with this value. The value given should be a positive integer value. A value of 0 disables rate limiting on the DependentPipelineManager. Default: 20.

window-floor

DependentPipelineManagers only. This is the minimum value for the window described above. Should be a positive non zero integer value. Default: 3.

window-increase-type

DependentPipelineManagers only. This value describes how the window should grow when changes are successfully merged by zuul. A value of linear indicates that window-increase-factor should be added to the previous window value. A value of exponential indicates that window-increase-factor should be multiplied against the previous window value and the result will become the window size. Default: linear.

window-increase-factor

DependentPipelineManagers only. The value to be added or mulitplied against the previous window value to determine the new window after successful change merges. Default: 1.

window-decrease-type

DependentPipelineManagers only. This value describes how the window should shrink when changes are not able to be merged by Zuul. A value of linear indicates that window-decrease-factor should be subtracted from the previous window value. A value of exponential indicates that window-decrease-factor should be divided against the previous window value and the result will become the window size. Default: exponential.

window-decrease-factor

DependentPipelineManagers only. The value to be subtracted or divided against the previous window value to determine the new window after unsuccessful change merges. Default: 2.

Some example pipeline configurations are included in the sample layout file. The first is called a check pipeline:

- name: check
  manager: IndependentPipelineManager
  trigger:
    - event: patchset-created
  success:
    gerrit:
      verified: 1
  failure:
    gerrit:
      verified: -1

This will trigger jobs each time a new patchset (or change) is uploaded to Gerrit, and report +/-1 values to Gerrit in the verified review category. :

- name: gate
  manager: DependentPipelineManager
  trigger:
    - event: comment-added
      approval:
        - approved: 1
  success:
    gerrit:
      verified: 2
      submit: true
  failure:
    gerrit:
      verified: -2

This will trigger jobs whenever a reviewer leaves a vote of 1 in the approved review category in Gerrit (a non-standard category). Changes will be tested in such a way as to guarantee that they will be merged exactly as tested, though that will happen in parallel by creating a virtual queue of dependent changes and performing speculative execution of jobs. :

- name: post
  manager: IndependentPipelineManager
  trigger:
    - event: ref-updated
      ref: ^(?!refs/).*$

This will trigger jobs whenever a change is merged to a named branch (e.g., master). No output will be reported to Gerrit. This is useful for side effects such as creating per-commit tarballs. :

- name: silent
  manager: IndependentPipelineManager
  trigger:
    - event: patchset-created

This also triggers jobs when changes are uploaded to Gerrit, but no results are reported to Gerrit. This is useful for jobs that are in development and not yet ready to be presented to developers. :

pipelines:
  - name: post-merge
    manager: IndependentPipelineManager
    trigger:
      - event: change-merged
    success:
      gerrit:
        force-message: True
    failure:
      gerrit:
        force-message: True

The change-merged events happen when a change has been merged in the git repository. The change is thus closed and Gerrit will not accept modifications to the review scoring such as code-review or verified. By using the force-message: True parameter, Zuul will pass --force-message to the gerrit review command, thus making sure the message is actually sent back to Gerrit regardless of approval scores. That kind of pipeline is nice to run regression or performance tests.

Note

The change-merged event does not include the commit sha1 which can be hazardous, it would let you report back to Gerrit though. If you were to build a tarball for a specific commit, you should consider instead using the ref-updated event which does include the commit sha1 (but lacks the Gerrit change number).

Jobs

The jobs section is optional, and can be used to set attributes of jobs that are independent of their association with a project. For example, if a job should return a customized message on failure, that may be specified here. Otherwise, Zuul does not need to be told about each job as it builds a list from the project specification.

name

The name of the job. This field is treated as a regular expression and will be applied to each job that matches.

failure-message (optional)

The message that should be reported to Gerrit if the job fails.

success-message (optional)

The message that should be reported to Gerrit if the job fails.

failure-pattern (optional)

The URL that should be reported to Gerrit if the job fails. Defaults to the build URL or the url_pattern configured in zuul.conf. May be supplied as a string pattern with substitutions as described in url_pattern in zuulconf.

success-pattern (optional)

The URL that should be reported to Gerrit if the job succeeds. Defaults to the build URL or the url_pattern configured in zuul.conf. May be supplied as a string pattern with substitutions as described in url_pattern in zuulconf.

hold-following-changes (optional)

This is a boolean that indicates that changes that follow this change in a dependent change pipeline should wait until this job succeeds before launching. If this is applied to a very short job that can predict whether longer jobs will fail early, this can be used to reduce the number of jobs that Zuul will launch and ultimately have to cancel. In that case, a small amount of parallelization of jobs is traded for more efficient use of testing resources. On the other hand, to apply this to a long running job would largely defeat the parallelization of dependent change testing that is the main feature of Zuul. Default: false.

branch (optional)

This job should only be run on matching branches. This field is treated as a regular expression and multiple branches may be listed.

files (optional)

This job should only be run if at least one of the files involved in the change (added, deleted, or modified) matches at least one of the file patterns listed here. This field is treated as a regular expression and multiple expressions may be listed.

voting (optional)

Boolean value (true or false) that indicates whatever a job is voting or not. Default: true.

parameter-function (optional)

Specifies a function that should be applied to the parameters before the job is launched. The function should be defined in a python file included with the includes directive. The function should have the following signature:

parameters(item, job, parameters)

Manipulate the parameters passed to a job before a build is launched. The parameters dictionary will already contain the standard Zuul job parameters, and is expected to be modified in-place.

param item

the current queue item

type item

zuul.model.QueueItem

param job

the job about to be run

type job

zuul.model.Job

param parameters

parameters to be passed to the job

type parameters

dict

If the parameter ZUUL_NODE is set by this function, then it will be used to specify on what node (or class of node) the job should be run.

Here is an example of setting the failure message for jobs that check whether a change merges cleanly:

- name: ^.*-merge$
  failure-message: This change was unable to be automatically merged
  with the current state of the repository. Please rebase your
  change and upload a new patchset.

Projects

The projects section indicates what jobs should be run in each pipeline for events associated with each project. It contains a list of projects. Here is an example:

- name: example/project
  check:
    - project-merge:
      - project-unittest
      - project-pep8
      - project-pyflakes
  gate:
    - project-merge:
      - project-unittest
      - project-pep8
      - project-pyflakes
  post:
    - project-publish

name

The name of the project (as known by Gerrit).

merge-mode (optional)

An optional value that indicates what strategy should be used to merge changes to this project. Supported values are:

** merge-resolve ** Equivalent to 'git merge -s resolve'. This corresponds closely to what Gerrit performs (using JGit) for a project if the "Merge if necessary" merge mode is selected and "Automatically resolve conflicts" is checked. This is the default.

** merge ** Equivalent to 'git merge'.

** cherry-pick ** Equivalent to 'git cherry-pick'.

This is followed by a section for each of the pipelines defined above. Pipelines may be omitted if no jobs should run for this project in a given pipeline. Within the pipeline section, the jobs that should be executed are listed. If a job is entered as a dictionary key, then jobs contained within that key are only executed if the key job succeeds. In the above example, project-unittest, project-pep8, and project-pyflakes are only executed if project-merge succeeds. This can help avoid running unnecessary jobs.

The OpenStack Zuul configuration for a comprehensive example: https://github.com/openstack-infra/config/blob/master/modules/openstack_project/files/zuul/layout.yaml

Project Templates

Whenever you have lot of similar projects (such as plugins for a project) you will most probably want to use the same pipeline configurations. The project templates let you define pipelines and job name templates to trigger. One can then just apply the template on its project which make it easier to update several similar projects. As an example:

project-templates:
  # Name of the template
  - name: plugin-triggering
    # Definition of pipelines just like for a `project`
    check:
     - '{jobprefix}-merge':
       - '{jobprefix}-pep8'
       - '{jobprefix}-pyflakes'
    gate:
     - '{jobprefix}-merge':
       - '{jobprefix}-unittest'
       - '{jobprefix}-pep8'
       - '{jobprefix}-pyflakes'

In your projects definition, you will then apply the template using the template key:

projects:
 - name: plugin/foobar
   template:
    - name: plugin-triggering
      jobprefix: plugin-foobar

You can pass several parameters to a template. A parameter value will be used for expansion of {parameter} in the template strings. The parameter name will be automatically provided and will contain the short name of the project, that is the portion of the project name after the last / character.

Multiple templates can be combined in a project, and the jobs from all of those templates will be added to the project. Individual jobs may also be added:

projects:
 - name: plugin/foobar
   template:
    - name: plugin-triggering
      jobprefix: plugin-foobar
    - name: plugin-extras
      jobprefix: plugin-foobar
   check:
    - foobar-extra-special-job

The order of the jobs listed in the project (which only affects the order of jobs listed on the report) will be the jobs from each template in the order listed, followed by any jobs individually listed for the project.

Note that if multiple templates are used for a project and one template specifies a job that is also specified in another template, or specified in the project itself, those jobs will be duplicated in the resulting project configuration.

logging.conf

This file is optional. If provided, it should be a standard logging.config module configuration file. If not present, Zuul will output all log messages of DEBUG level or higher to the console.

Starting Zuul

To start Zuul, run zuul-server:

usage: zuul-server [-h] [-c CONFIG] [-l LAYOUT] [-d] [-t] [--version]

Project gating system.

optional arguments:
  -h, --help  show this help message and exit
  -c CONFIG   specify the config file
  -l LAYOUT   specify the layout file
  -d          do not run as a daemon
  -t          validate layout file syntax
  --version   show zuul version

You may want to use the -d argument while you are initially setting up Zuul so you can detect any configuration errors quickly. Under normal operation, omit -d and let Zuul run as a daemon.

If you send signal 1 (SIGHUP) to the zuul-server process, Zuul will stop executing new jobs, wait until all executing jobs are finished, reload its configuration, and resume. Any values in any of the configuration files may be changed, except the location of Zuul's PID file (a change to that will be ignored until Zuul is restarted).

If you send a SIGUSR1 to the zuul-server process, Zuul will stop executing new jobs, wait until all executing jobs are finished, then exit. While waiting to exit Zuul will queue Gerrit events and save these events prior to exiting. When Zuul starts again it will read these saved events and act on them.

If you need to abort Zuul and intend to manually requeue changes for jobs which were running in its pipelines, prior to terminating you can use the zuul-changes.py tool script to simplify the process. For example, this would give you a list of Gerrit commands to reverify or recheck changes for the gate and check pipelines respectively:

./tools/zuul-changes.py --review-host=review.openstack.org \
    http://zuul.openstack.org/ gate 'reverify no bug'
./tools/zuul-changes.py --review-host=review.openstack.org \
    http://zuul.openstack.org/ check 'recheck no bug'

If you send a SIGUSR2 to the zuul-server process, Zuul will dump a stack trace for each running thread into its debug log. This is useful for tracking down deadlock or otherwise slow threads.