Navigation

Wherever possible, Buildbot components should access configuration information
as needed from the canonical source, master.config, which is an instance of
MasterConfig. For example, components should not keep a copy of
the buildbotURL locally, as this value may change throughout the lifetime
of the master.

The master object makes much of the configuration available from an object
named master.config. Configuration is stored as attributes of this
object. Where possible, other Buildbot components should access this
configuration directly and not cache the configuration values anywhere
else. This avoids the need to ensure that update-from-configuration
methods are called on a reconfig.

Aside from validating the configuration, this class handles any
backward-compatibility issues - renamed parameters, type changes, and so on
- removing those concerns from other parts of Buildbot.

This class may be instantiated directly, creating an entirely default
configuration, or via FileLoader.loadConfig, which will load the
configuration from a config file.

The following attributes are available from this class, representing the
current configuration. This includes a number of global parameters:

This class parameterizes configuration of builders; see
Builder Configuration for its arguments. The constructor checks for
errors and applies defaults, and sets the properties described here. Most
are simply copied from the constructor argument of the same name.

If any errors are encountered while loading the configuration buildbot.config.error
should be called. This can occur both in the configuration-loading code,
and in the constructors of any objects that are instantiated in the
configuration - change sources, workers, schedulers, build steps, and so on.

This function reports a configuration error. If a config file is being loaded,
then the function merely records the error, and allows the rest of the configuration
to be loaded. At any other time, it raises ConfigErrors. This is done
so all config errors can be reported, rather than just the first.

When the buildmaster receives a signal to begin a reconfig, it re-reads the
configuration file, generating a new MasterConfig instance, and
then notifies all of its child services via the reconfig mechanism described
below. The master ensures that at most one reconfiguration is taking place at
any time.

To simplify initialization, a reconfiguration is performed immediately on
master startup. As a result, services only need to implement their
configuration handling once, and can use startService for initialization.

See below for instructions on implementing configuration of common types of
components in Buildbot.

Note

Because Buildbot uses a pure-Python configuration file, it is not possible
to support all forms of reconfiguration. In particular, when the
configuration includes custom subclasses or modules, reconfiguration can
turn up some surprising behaviors due to the dynamic nature of Python. The
reconfig support in Buildbot is intended for "intermediate" uses of the
software, where there are fewer surprises.

This method notifies the service that it should make any changes
necessary to adapt to the new configuration values given.

This method will be called automatically after a service is started.

It is generally too late at this point to roll back the
reconfiguration, so if possible any errors should be detected in the
MasterConfig implementation. Errors are handled as best as
possible and communicated back to the top level invocation, but such
errors may leave the master in an inconsistent state.
ConfigErrors exceptions will be displayed appropriately to
the user on startup.

Subclasses should always call the parent class's implementation. For
MultiService instances, this will call any child services'
reconfigService methods, as appropriate. This will be done
sequentially, such that the Deferred from one service must fire before
the next service is reconfigured.

When reconfiguring, there is no method by which Buildbot can determine that a
new ChangeSource represents the same source
as an existing ChangeSource, but with
different configuration parameters. As a result, the change source manager
compares the lists of existing and new change sources using equality, stops any
existing sources that are not in the new list, and starts any new change
sources that do not already exist.

If a change source does not make reference to any global configuration
parameters, then there is no need to inherit
ReconfigurableServiceMixin, as a simple comparison and
startService and stopService will be sufficient.

If the change source does make reference to global values, e.g., as default
values for its parameters, then it must inherit
ReconfigurableServiceMixin to support the case where the global
values change.

Schedulers have names, so Buildbot can determine whether a scheduler has been
added, removed, or changed during a reconfig. Old schedulers will be stopped,
new schedulers will be started, and both new and existing schedulers will see a
call to reconfigService, if such a
method exists. For backward compatibility, schedulers which do not support
reconfiguration will be stopped, and the new scheduler started, when their
configuration changes.

If, during a reconfiguration, a new and old scheduler's fully qualified class
names differ, then the old class will be stopped and the new class started.
This supports the case when a user changes, for example, a Nightly scheduler to a Periodic scheduler without changing the name.

Because Buildbot uses BaseScheduler
instances directly in the configuration file, a reconfigured scheduler must
extract its new configuration information from another instance of itself.

Custom subclasses are most often defined directly in the configuration file, or
in a Python module that is reloaded with reload every time the
configuration is loaded. Because of the dynamic nature of Python, this creates
a new object representing the subclass every time the configuration is loaded
-- even if the class definition has not changed.

Note that if a scheduler's class changes in a reconfig, but the scheduler's
name does not, it will still be treated as a reconfiguration of the existing
scheduler. This means that implementation changes in custom scheduler
subclasses will not be activated with a reconfig. This behavior avoids
stopping and starting such schedulers on every reconfig, but can make
development difficult.

One workaround for this is to change the name of the scheduler before each
reconfig - this will cause the old scheduler to be stopped, and the new
scheduler (with the new name and class) to be started.

Similar to schedulers, workers are specified by name, so new and old
configurations are first compared by name, and any workers to be added or
removed are noted. Workers for which the fully-qualified class name has changed
are also added and removed. All workers have their
reconfigService method called.

This method takes care of the basic worker attributes, including changing the PB
registration if necessary. Any subclasses that add configuration parameters
should override reconfigService and
update those parameters. As with Schedulers, because the
AbstractWorker instance is given directly
in the configuration, on reconfig instances must extract the configuration from
a new instance.