Add documentation.

Change-Id: I8197ec2e52596fa4136f8af9aa93ea06e56d4d0d
James E. Blair 11 years ago
parent 4baa94cb06
commit cdd000764e

.gitignore vendored

@ -4,3 +4,6 @@ zuul.egg-info

@ -0,0 +1,153 @@
# Makefile for Sphinx documentation
# You can set these variables from the command line.
SPHINXBUILD = sphinx-build
BUILDDIR = build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
# the i18n builder cannot share the environment and doctrees with the others
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
-rm -rf $(BUILDDIR)/*
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
@echo "Build finished; now you can process the pickle files."
@echo "Build finished; now you can process the JSON files."
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Zuul.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Zuul.qhc"
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/Zuul"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Zuul"
@echo "# devhelp"
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
@echo "Build finished. The text files are in $(BUILDDIR)/text."
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
@echo "The overview file is in $(BUILDDIR)/changes."
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."

@ -0,0 +1,244 @@
# -*- coding: utf-8 -*-
# Zuul documentation build configuration file, created by
# sphinx-quickstart on Fri Jun 8 14:44:26 2012.
# This file is execfile()d with the current directory set to its containing dir.
# Note that not all possible configuration values are present in this
# autogenerated file.
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys, os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.intersphinx']
intersphinx_mapping = {'python': ('', None)}
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Zuul'
copyright = u'2012, OpenStack'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
# The short X.Y version.
version = '1.0'
# The full version, including alpha/beta/rc tags.
release = '1.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'Zuuldoc'
# -- Options for LaTeX output --------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'Zuul.tex', u'Zuul Documentation',
u'OpenStack', 'manual'),
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'zuul', u'Zuul Documentation',
[u'OpenStack'], 1)
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output ------------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'Zuul', u'Zuul Documentation',
u'OpenStack', 'Zuul', 'One line description of project.',
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'

@ -0,0 +1,96 @@
:title: Project Gating
Project Gating
Traditionally, many software development projects merge changes from
developers into the repository, and then identify regressions
resulting from those changes (perhaps by running a test suite with a
continuous integration system such as Jenkins), followed by more
patches to fix those bugs. When the mainline of development is
broken, it can be very frustrating for developers and can cause lost
productivity, particularly so when the number of contributors or
contributions is large.
The process of gating attempts to prevent changes that introduce
regressions from being merged. This keeps the mainline of development
open and working for all developers, and only when a change is
confirmed to work without disruption is it merged.
Many projects practice an informal method of gating where developers
with mainline commit access ensure that a test suite runs before
merging a change. With more developers, more changes, and more
comprehensive test suites, that process does not scale very well, and
is not the best use of a developer's time. Zuul can help automate
this process, with a particular emphasis on ensuring large numbers of
changes are tested correctly.
Zuul was designed to handle the workflow of the OpenStack project, but
can be used with any project.
A particular focus of Zuul is ensuring correctly ordered testing of
changes in parallel. A gating system should always test each change
applied to the tip of the branch exactly as it is going to be merged.
A simple way to do that would be to test one change at a time, and
merge it only if it passes tests. That works very well, but if
changes take a long time to test, developers may have to wait a long
time for their changes to make it into the repository. With some
projects, it may take hours to test changes, and it is easy for
developers to create changes at a rate faster than they can be tested
and merged.
Zuul's DependentQueueManager allows for parallel execution of test
jobs for gating while ensuring changes are tested correctly, exactly
as if they had been tested one at a time. It does this by performing
speculative execution of test jobs; it assumes that all jobs will
succeed and tests them in parallel accordingly. If they do succeed,
they can all be merged. However, if one fails, then changes that were
expecting it to succeed are re-tested without the failed change. In
the best case, as many changes as execution contexts are available may
be tested in parallel and merged at once. In the worst case, changes
are tested one at a time (as each subsequent change fails, changes
behind it start again). In practice, the OpenStack project observes
something closer to the best case.
For example, if a core developer approves five changes in rapid
A, B, C, D, E
Zuul queues those changes in the order they were approved, and notes
that each subsequent change depends on the one ahead of it merging::
A <-- B <-- C <-- D <-- E
Zuul then starts immediately testing all of the changes in parallel.
But in the case of changes that depend on others, it instructs the
test system to include the changes ahead of it, with the assumption
they pass. That means jobs testing change *B* include change *A* as
Jobs for A: merge change A, then test
Jobs for B: merge changes A and B, then test
Jobs for C: merge changes A, B and C, then test
Jobs for D: merge changes A, B, C and D, then test
Jobs for E: merge changes A, B, C, D and E, then test
If changes *A* and *B* pass tests, and *C*, *D*, and *E* fail::
A[pass] <-- B[pass] <-- C[fail] <-- D[fail] <-- E[fail]
Zuul will merge change *A* followed by change *B*, leaving this queue::
C[fail] <-- D[fail] <-- E[fail]
Since *D* was dependent on *C*, it is not clear whether *D*'s failure is the
result of a defect in *D* or *C*::
C[fail] <-- D[unknown] <-- E[unknown]
Since *C* failed, it will report the failure and drop *C* from the queue::
D[unknown] <-- E[unknown]
This queue is the same as if two new changes had just arrived, so Zuul
starts the process again testing *D* against the tip of the branch, and
*E* against *D*.

@ -0,0 +1,32 @@
.. Zuul documentation master file, created by
sphinx-quickstart on Fri Jun 8 14:44:26 2012.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Zuul - A Project Gating System
Zuul is a program that is used to gate the source code repository of a
project so that changes are only merged if they pass tests.
The main component of Zuul is the scheduler. It receives events
related to proposed changes (currently from Gerrit), triggers tests
based on those events (currently on Jenkins), and reports back.
.. toctree::
:maxdepth: 2
Indices and tables
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

@ -0,0 +1,105 @@
:title: Launchers
Zuul has a modular architecture for launching jobs. Currently only
Jenkins is supported, but it should be fairly easy to add a module to
support other systems. Zuul makes very few assumptions about the
interface to a launcher -- if it can trigger jobs, cancel them, and
receive success or failure reports, it should be able to be used with
Zuul. Patches to this effect are welcome.
Zuul works with Jenkins using the Jenkins API and the notification
module. It uses the Jenkins API to trigger jobs, passing in
parameters indicating what should be tested. It recieves
notifications on job completion via the notification API (so jobs must
be conifigured to notify Zuul).
Jenkins Configuration
Zuul will need access to a Jenkins user. Create a user in Jenkins,
and then visit the configuration page for the user:
And click **Show API Token** to retrieve the API token for that user.
You will need this later when configuring Zuul. Make sure that this
user has appropriate permission to build any jobs that you want Zuul
to trigger.
Make sure the notification plugin is installed. Visit the plugin
manager on your jenkins:
And install **Jenkins Notification plugin**. The homepage for the
plugin is at:
Jenkins Job Configuration
For each job that you want Zuul to trigger, you will need to add a
notification endpoint for the job on that job's configuration page.
Click **Add Endpoint** and enter the following values:
If you are running Zuul on a different server than Jenkins, enter the
appropriate URL. Note that Zuul itself has no access controls, so
ensure that only Jenkins is permitted to access that URL.
Zuul will pass some parameters to Jenkins for every job it launches.
Check **This build is parameterized**, and add the following fields
with the type **String Parameter**:
Zuul provided key to link builds with Gerrit events
Zuul provided project name
Zuul provided branch name
Zuul provided list of dependent changes to merge
You may find it useful to use the ``GERRIT_*`` variables in your job.
In particular, ``GERRIT_CHANGES`` indicates the change or changes that
should be tested. If Zuul has decided that more than one change
should be merged and tested together, they will all be listed in
``GERRIT_CHANGES``. The format for the description of one change is::
And multiple changes are separated by a carat ("^"). E.g.::
The OpenStack project uses the following script to update the
repository in a workspace and merge appropriate changes:
Gerrit events that do not include a change (e.g., ref-updated events
which are emitted after a git ref is updated (i.e., a commit is merged
to master)) require a slightly different set of parameters:
Zuul provided key to link builds with Gerrit events
Zuul provided project name
Zuul provided ref name
Zuul provided old reference for ref-updated
Zuul provided new reference for ref-updated

@ -0,0 +1,37 @@
:title: Triggers
The process of merging a change starts with proposing a change to be
merged. Currently Zuul only supports Gerrit as a triggering system.
Zuul's design is modular, so alternate triggering and reporting
systems can be supported. However, Gerrit has a particularly robust
data model, and Zuul does make some assumptions that include that data
model. Nonetheless, patches to support alternate systems are welcome.
Zuul works with standard versions of Gerrit by invoking the ``gerrit
stream-events`` command over an SSH connection. It also reports back
to Gerrit using SSH.
Gerrit Configuration
Zuul will need access to a Gerrit user. Consider naming the user
*Jenkins* so that developers see that feedback from changes is from
Jenkins (Zuul attempts to stay out of the way of developers, most
shouldn't even need to know it's there).
Create an SSH keypair for Zuul to use if there isn't one already, and
create a Gerrit user with that key::
cat ~/ | ssh -p29418 gerrit create-account --ssh-key - --full-name Jenkins jenkins
Give that user whatever permissions will be needed on the projects you
want Zuul to gate. For instance, you may want to grant ``Verified
+/-1`` and ``Submit`` to the user. Additional categories or values may
be added to Gerrit. Zuul is very flexible and can take advantage of

@ -0,0 +1,319 @@
:title: Zuul
Zuul has three configuration files:
Credentials for Gerrit and Jenkins, locations of the other config files
Project and queue configuration -- what Zuul does
Python logging config
Examples of each of the three files can be found in the etc/ directory
of the source distribution.
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 Jenkins credentials 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.
This is the main configuration file for Zuul, where all of the queues
and projects are defined, what tests should be run, and what actions
Zuul should perform. There are three sections: queues, jobs, and
Zuul can have any number of independent queues. Whenever a matching
Gerrit event is found for a queue, that event is added to the queue,
and the jobs specified for that queue are run. When all jobs
specified for the queue that were triggered by an event are completed,
Zuul reports back to Gerrit the results.
There are no pre-defined queues in Zuul, rather you can define
whatever queues 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 queue definition followed by an
explanation of each of the parameters::
- name: check
manager: IndependentQueueManager
- event: patchset-created
verified: 1
verified: -1
This is used later in the project definition to indicate what jobs
should be run for events in the queue.
There are currently two schemes for managing queues:
Every event in this queue should be treated as independent of
other events in the queue. This is appropriate when the order of
events in the queue doesn't matter because the results of the
actions this queue performs can not affect other events in the
queue. 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 queue. They are independent.
Another type of queue that is independent is a post-merge queue.
In that case, the changes have already merged, so the results can
not affect any other events in the queue.
The dependent queue 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 queue manager performs
speculative execution on changes. It orders changes based on
their entry into the queue. It begins testing all changes in
parallel, assuming that each change ahead in the queue 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 queue 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 DependentQueueManager 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
DependentQueueManager, see: :doc:`gating`.
This describes what Gerrit events should be placed in the queue.
Triggers are not exclusive -- matching events may be placed in
multiple queues, and they will behave independently in each of the
queues they match. Multiple triggers may be listed. Further
parameters describe the kind of events that match:
The event name from gerrit. Examples: ``patchset-created``,
``comment-added``, ``ref-updated``. This field is treated as a
regular expression.
The branch associated with the event. Example: ``master``. This
field is treated as a regular expression, and multiple branches may
be listed.
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.
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.
Describes what Zuul should do 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, it will leave a message on the Gerrit
review. Each additional argument is assumed to be an argument to
``gerrit review``, with the boolean value of ``true`` simply
indicating that the argument should be present without following it
with a value. For example, ``verified: 1`` becomes ``gerrit
review --verified 1`` and ``submit: true`` becomes ``gerrit review
Uses the same syntax as **success**, but describes what Zuul should
do if at least one job fails.
Some example queue configurations are included in the sample layout
file. The first is called a *check* queue::
- name: check
manager: IndependentQueueManager
- event: patchset-created
verified: 1
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: DependentQueueManager
- event: comment-added
- approved: 1
verified: 2
submit: true
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: IndependentQueueManager
- 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: IndependentQueueManager
- 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.
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.
The name of the job. This field is treated as a regular expression
and will be applied to each job that matches.
The message that should be reported to Gerrit if the job fails
The message that should be reported to Gerrit if the job fails
This job should only be run on matching branches. This field is
treated as a regular expression and multiple branches may be
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.
The projects section indicates what jobs should be run in each queue
for events associated with each project. It contains a list of
projects. Here is an example::
- name: example/project
- project-merge:
- project-unittest
- project-pep8
- project-pyflakes
- project-merge:
- project-unittest
- project-pep8
- project-pyflakes
- project-publish
The name of the project (as known by Gerrit).
This is followed by a section for each of the queues defined above.
Queues may be omitted if no jobs should run for this project in a
given queue. Within the queue 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.
.. seealso:: The OpenStack Zuul configuration for a comprehensive example:
This file is optional. If provided, it should be a standard
:mod:`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] [-d]
Project gating system.
optional arguments:
-h, --help show this help message and exit
-c CONFIG specify the config file
-d do not run as a daemon
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).

@ -2,7 +2,7 @@ queues:
- name: check
manager: IndependentQueueManager
- event: patchset-uploaded
- event: patchset-created
verified: 1

@ -0,0 +1,4 @@
source-dir = doc/source
build-dir = doc/build
all_files = 1

@ -1,10 +1,19 @@
envlist = pep8, pyflakes
downloadcache = ~/cache/pip
deps = pep8
commands = pep8 --repeat --show-source zuul zuul-server
commands = pep8 --repeat --show-source --exclude=.venv,.tox,dist,doc .
deps = pyflakes
commands = pyflakes zuul zuul-server
commands = {posargs}