The buildbot's behavior is defined by the config file, which
normally lives in the master.cfg file in the buildmaster's base
directory (but this can be changed with an option to the
buildbot create-master command). This file completely specifies
which Builders are to be run, which slaves they should use, how
Changes should be tracked, and where the status information is to be
sent. The buildmaster's buildbot.tac file names the base
directory; everything else comes from the config file.

A sample config file was installed for you when you created the
buildmaster, but you will need to edit it before your buildbot will do
anything useful.

This chapter gives an overview of the format of this file and the
various sections in it. You will need to read the later chapters to
understand how to fill in each section properly.

The config file is, fundamentally, just a piece of Python code which
defines a dictionary named BuildmasterConfig, with a number of
keys that are treated specially. You don't need to know Python to do
basic configuration, though, you can just copy the syntax of the
sample file. If you are comfortable writing Python code,
however, you can use all the power of a full programming language to
achieve more complicated configurations.

The BuildmasterConfig name is the only one which matters: all
other names defined during the execution of the file are discarded.
When parsing the config file, the Buildmaster generally compares the
old configuration with the new one and performs the minimum set of
actions necessary to bring the buildbot up to date: Builders which are
not changed are left untouched, and Builders which are modified get to
keep their old event history.

The beginning of the master.cfg file
typically starts with something like:

BuildmasterConfig=c={}

Therefore a config key like change_source will usually appear in
master.cfg as c['change_source'].

The master configuration file is interpreted as Python, allowing the full
flexibility of the language. For the configurations described in this section,
a detailed knowledge of Python is not required, but the basic syntax is easily
described.

Python comments start with a hash character #, tuples are defined with
(parenthesis,pairs), and lists (arrays) are defined with [square,brackets]. Tuples and lists are mostly interchangeable. Dictionaries (data
structures which map keys to values) are defined with curly braces:
{'key1':value1,'key2':value2}. Function calls (and object
instantiation) can use named parameters, like w=html.Waterfall(http_port=8010).

The config file starts with a series of import statements, which make
various kinds of Steps and Status targets available for
later use. The main BuildmasterConfig dictionary is created, then it is
populated with a variety of keys, described section-by-section in subsequent
chapters.

If the config file has deprecated features (perhaps because you've
upgraded the buildmaster and need to update the config file to match),
they will be announced by checkconfig. In this case, the config file
will work, but you should really remove the deprecated items and use
the recommended replacements instead:

% buildbot checkconfig master.cfg
/usr/lib/python2.4/site-packages/buildbot/master.py:559: DeprecationWarning: c['sources'] is
deprecated as of 0.7.6 and will be removed by 0.8.0 . Please use c['change_source'] instead.
Config file is good!

If you have errors in your configuration file, checkconfig will let you know:

If you are on the system hosting the buildmaster, you can send a SIGHUP
signal to it: the buildbot tool has a shortcut for this:

buildbot reconfig BASEDIR

This command will show you all of the lines from twistd.log
that relate to the reconfiguration. If there are any problems during
the config-file reload, they will be displayed in these lines.

When reloading the config file, the buildmaster will endeavor to
change as little as possible about the running system. For example,
although old status targets may be shut down and new ones started up,
any status targets that were not changed since the last time the
config file was read will be left running and untouched. Likewise any
Builders which have not been changed will be left running. If a
Builder is modified (say, the build process is changed) while a Build
is currently running, that Build will keep running with the old
process until it completes. Any previously queued Builds (or Builds
which get queued after the reconfig) will use the new process.

Warning

Buildbot's reconfiguration system is fragile for a few difficult-to-fix
reasons:

Any modules imported by the configuration file are not automatically reloaded.
Python modules such as http://pypi.python.org/pypi/lazy-reload may help
here, but reloading modules is fraught with subtleties and difficult-to-decipher
failure cases.

During the reconfiguration, active internal objects are divorced from the service
hierarchy, leading to tracebacks in the web interface and other components. These
are ordinarily transient, but with HTTP connection caching (either by the browser or
an intervening proxy) they can last for a long time.

If the new configuration file is invalid, it is possible for Buildbot's
internal state to be corrupted, leading to undefined results. When this
occurs, it is best to restart the master.

For more advanced configurations, it is impossible for Buildbot to tell if the
configuration for a Builder or Scheduler has changed, and thus the Builder or
Scheduler will always be reloaded. This occurs most commonly when a callable
is passed as a configuration parameter.