Wherever possible, Buildbot components should access configuration information as needed from the canonical source, master.config, which is an instance of :pyMasterConfig. For example, components should not keep a copy of the buildbotURL locally, as this value may change throughout the lifetime of the master.
Components which need to be notified of changes in the configuration should be implemented as services, subclassing :pyReconfigurableServiceMixin, as described in developer-Reconfiguration.
Loading of the configuration file is generally triggered by the master, using the following class:
If any errors are encountered while loading the configuration :pybuildbot.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.
The AngularJS frontend often needs access to the local master configuration. This is accomplished automatically by converting various pieces of the master configuration to a dictionary.
The :py~buildbot.interfaces.IConfigured interface represents a way to convert any object into a JSON-able dictionary.
Providers of this interface provide a method to get their configuration as a dictionary:
getConfigDict()
- returns
object
Return the configuration of this object. Note that despite the name, the return value may not be a dictionary.
Any object can be "cast" to an :py
~buildbot.interfaces.IConfiguredprovider. ThegetConfigDictmethod for basic Python objects simply returns the value. :IConfigured(someObject).getConfigDict()
All of this is used by to serve /config.js to the JavaScript frontend.
When the buildmaster receives a signal to begin a reconfig, it re-reads the configuration file, generating a new :pyMasterConfig 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.
See master-service-hierarchy for the structure of the Buildbot service tree.
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.
Service Mixins; ReconfigurableServiceMixin
Instances which need to be notified of a change in configuration should be implemented as Twisted services, and mix in the :pyReconfigurableServiceMixin class, overriding the :py~ReconfigurableServiceMixin.reconfigServiceWithBuildbotConfig method.
When reconfiguring, there is no method by which Buildbot can determine that a new :py~buildbot.changes.base.ChangeSource represents the same source as an existing :py~buildbot.changes.base.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.
:py~buildbot.changes.base.ChangeSource inherits :py~buildbot.util.ComparableMixin, so change sources are compared based on the attributes described in their compare_attrs.
If a change source does not make reference to any global configuration parameters, then there is no need to inherit :pyReconfigurableServiceMixin, 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 :pyReconfigurableServiceMixin 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 :py~ReconfigurableServiceMixin.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 :bbNightly scheduler to a :bbPeriodic scheduler without changing the name.
Because Buildbot uses :py~buildbot.schedulers.base.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 :py~ReconfigurableServiceMixin.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 :py~ReconfigurableServiceMixin.reconfigService and update those parameters. As with Schedulers, because the :py~buildbot.worker.AbstractWorker instance is given directly in the configuration, on reconfig instances must extract the configuration from a new instance.
Since user managers are rarely used, and their purpose is unclear, they are always stopped and re-started on every reconfig. This may change in figure versions.
At every reconfig, all status listeners are stopped and new versions started.