This is the Buildbot documentation for Buildbot version 4.0.4.

If you are evaluating Buildbot and would like to get started quickly, start with the Tutorial. Regular users of Buildbot should consult the Manual, and those wishing to modify Buildbot directly will want to be familiar with the Developer’s Documentation.

Table Of Contents

1. Buildbot Tutorial

Contents:

1.1. First Run

1.1.1. Goal

This tutorial will take you from zero to running your first buildbot master and worker as quickly as possible, without changing the default configuration.

This tutorial is all about instant gratification and the five minute experience: in five minutes we want to convince you that this project works, and that you should seriously consider spending time learning the system. In this tutorial no configuration or code changes are done.

This tutorial assumes that you are running Unix, but might be adaptable to Windows.

Thanks to virtualenv, installing buildbot in a standalone environment is very easy. For those more familiar with Docker, there also exists a docker version of these instructions.

You should be able to cut and paste each shell block from this tutorial directly into a terminal.

1.1.2. Simple introduction to BuildBot

Before trying to run BuildBot it’s helpful to know what BuildBot is.

BuildBot is a continuous integration framework written in Python. It consists of a master daemon and potentially many worker daemons that usually run on other machines. The master daemon runs a web server that allows the end user to start new builds and to control the behaviour of the BuildBot instance. The master also distributes builds to the workers. The worker daemons connect to the master daemon and execute builds whenever master tells them to do so.

In this tutorial we will run a single master and a single worker on the same machine.

A more thorough explanation can be found in the manual section of the Buildbot documentation.

1.1.3. Getting ready

There are many ways to get the code on your machine. We will use the easiest one: via pip in a virtualenv. It has the advantage of not polluting your operating system, as everything will be contained in the virtualenv.

To make this work, you will need the following installed:

Python and the development packages for it
virtualenv

Preferably, use your distribution package manager to install these.

You will also need a working Internet connection, as virtualenv and pip will need to download other projects from the Internet. The master and builder daemons will need to be able to connect to github.com via HTTPS to fetch the repo we’re testing.

If you need to use a proxy for this ensure that either the HTTPS_PROXY or ALL_PROXY environment variable is set to your proxy, e.g., by executing export HTTPS_PROXY=http://localhost:9080 in the shell before starting each daemon.

Note

Buildbot does not require root access. Run the commands in this tutorial as a normal, unprivileged user.

1.1.4. Creating a master

The first necessary step is to create a virtualenv for our master. We first create a separate directory to demonstrate the distinction between a master and worker:

mkdir -p ~/buildbot-test/master_root
cd ~/buildbot-test/master_root

Then we create the virtual environment. On Python 3:

python3 -m venv sandbox
source sandbox/bin/activate

Next, we need to install several build dependencies to make sure we can install buildbot and its supporting packages. These build dependencies are:

GCC build tools (gcc for RHEL/CentOS/Fedora based distributions, or build-essential for Ubuntu/Debian based distributions).
Python development library (python3-devel for RHEL/CentOS/Fedora based distributions, or python3-dev for Ubuntu/Debian based distributions).
OpenSSL development library (openssl-devel for RHEL/CentOS/Fedora based distributions, or libssl-dev for Ubuntu/Debian based distributions).
libffi development library (libffi-devel for RHEL/CentOS/Fedora based distributions, or libffi-dev for Ubuntu/Debian based distributions).

Install these build dependencies:

# if in Ubuntu/Debian based distributions:
sudo apt-get install build-essential python3-dev libssl-dev libffi-dev

# if in RHEL/CentOS/Fedora based distributions:
sudo yum install gcc python3-devel openssl-devel libffi-devel

or refer to your distribution’s documentation on how to install these packages.

Now that we are ready, we need to install buildbot:

pip install --upgrade pip
pip install 'buildbot[bundle]'

Now that buildbot is installed, it’s time to create the master. my_master represents a path to a directory, where future master will be created:

buildbot create-master my_master

Buildbot’s activity is controlled by a configuration file. Buildbot by default uses configuration from file at master.cfg, but its installation comes with a sample configuration file named master.cfg.sample. We will use the sample configuration file unchanged, but we have to rename it to master.cfg:

mv my_master/master.cfg.sample my_master/master.cfg

Finally, start the master:

buildbot start my_master

You will now see some log information from the master in this terminal. It should end with lines like these:

2014-11-01 15:52:55+0100 [-] BuildMaster is running
The buildmaster appears to have (re)started correctly.

From now on, feel free to visit the web status page running on the port 8010: http://localhost:8010/

Our master now needs (at least) one worker to execute its commands. For that, head on to the next section!

1.1.5. Creating a worker

The worker will be executing the commands sent by the master. In this tutorial, we are using the buildbot/hello-world project as an example. As a consequence of this, your worker will need access to the git command in order to checkout some code. Be sure that it is installed, or the builds will fail.

Same as we did for our master, we will create a virtualenv for our worker next to the master’s one. It would however be completely ok to do this on another computer - as long as the worker computer is able to connect to the master’s . We first create a new directory for the worker:

mkdir -p ~/buildbot-test/worker_root
cd ~/buildbot-test/worker_root

Again, we create a virtual environment. On Python 3:

python3 -m venv sandbox
source sandbox/bin/activate

Install the buildbot-worker command:

pip install --upgrade pip
pip install buildbot-worker
# required for `runtests` build
pip install setuptools-trial

Now, create the worker:

buildbot-worker create-worker my_worker localhost example-worker pass

Note

If you decided to create this from another computer, you should replace localhost with the name of the computer where your master is running.

The username (example-worker), and password (pass) should be the same as those in my_master/master.cfg; verify this is the case by looking at the section for c['workers']:

cat ../master_root/my_master/master.cfg

And finally, start the worker:

buildbot-worker start my_worker

Check the worker’s output. It should end with lines like these:

2014-11-01 15:56:51+0100 [-] Connecting to localhost:9989
2014-11-01 15:56:51+0100 [Broker,client] message from master: attached
The worker appears to have (re)started correctly.

Meanwhile, from the other terminal, in the master log (twisted.log in the master directory), you should see lines like these:

2014-11-01 15:56:51+0100 [Broker,1,127.0.0.1] worker 'example-worker' attaching from
IPv4Address(TCP, '127.0.0.1', 54015)
2014-11-01 15:56:51+0100 [Broker,1,127.0.0.1] Got workerinfo from 'example-worker'
2014-11-01 15:56:51+0100 [-] bot attached

1.1.6. Wrapping up

Your directory tree now should look like this:

~/buildbot-test/master_root/my_master  # master base directory
~/buildbot-test/master_root/sandbox    # virtualenv for master

~/buildbot-test/worker_root/my_worker  # worker base directory
~/buildbot-test/worker_root/sandbox    # virtualenv for worker

You should now be able to go to http://localhost:8010, where you will see a web page similar to:

Click on “Builds” at the left to open the submenu and then Builders to see that the worker you just started (identified by the green bubble) has connected to the master:

Your master is now quietly waiting for new commits to hello-world. This doesn’t happen very often though. In the next section, we’ll see how to manually start a build.

We just wanted to get you to dip your toes in the water. It’s easy to take your first steps, but this is about as far as we can go without touching the configuration.

You’ve got a taste now, but you’re probably curious for more. Let’s step it up a little in the second tutorial by changing the configuration and doing an actual build. Continue on to A Quick Tour.

1.2. A Quick Tour

1.2.1. Goal

This tutorial will expand on the First Run tutorial by taking a quick tour around some of the features of buildbot that are hinted at in the comments in the sample configuration. We will simply change parts of the default configuration and explain the activated features.

As a part of this tutorial, we will make buildbot do a few actual builds.

This section will teach you how to:

make simple configuration changes and activate them
deal with configuration errors
force builds
enable and control the IRC bot
add a ‘try’ scheduler

1.2.2. The First Build

On the Builders page, click on the runtests link. You’ll see a builder page, and a blue “force” button that will bring up the following dialog box:

Click Start Build - there’s no need to fill in any of the fields in this case. Next, click on view in waterfall.

You will now see that a successful test run has happened:

This simple process is essentially the whole purpose of the Buildbot project.

The information about what actions are executed for a certain build are defined in things called builders.

The information about when a certain builder should launch a build are defined in things called schedulers. In fact, the blue “force” button that was pushed in this example activated a scheduler too.

1.2.3. Setting Project Name and URL

Let’s start simple by looking at where you would customize the buildbot’s project name and URL.

We continue where we left off in the First Run tutorial.

Open a new terminal, go to the directory you created master in, activate the same virtualenv instance you created before, and open the master configuration file with an editor (here $EDITOR is your editor of choice like vim, gedit, or emacs):

cd ~/buildbot-test/master
source sandbox/bin/activate
$EDITOR master/master.cfg

Now, look for the section marked PROJECT IDENTITY which reads:

####### PROJECT IDENTITY

# the 'title' string will appear at the top of this buildbot installation's
# home pages (linked to the 'titleURL').

c['title'] = "Hello World CI"
c['titleURL'] = "https://buildbot.github.io/hello-world/"

If you want, you can change either of these links to anything you want so that you can see what happens when you change them.

After making a change, go to the terminal and type:

buildbot reconfig master

You will see a handful of lines of output from the master log, much like this:

2011-12-04 10:11:09-0600 [-] loading configuration from /path/to/buildbot/master.cfg
2011-12-04 10:11:09-0600 [-] configuration update started
2011-12-04 10:11:09-0600 [-] builder runtests is unchanged
2011-12-04 10:11:09-0600 [-] removing IStatusReceiver <...>
2011-12-04 10:11:09-0600 [-] (TCP Port 8010 Closed)
2011-12-04 10:11:09-0600 [-] Stopping factory <...>
2011-12-04 10:11:09-0600 [-] adding IStatusReceiver <...>
2011-12-04 10:11:09-0600 [-] RotateLogSite starting on 8010
2011-12-04 10:11:09-0600 [-] Starting factory <...>
2011-12-04 10:11:09-0600 [-] Setting up http.log rotating 10 files of 10000000 bytes each
2011-12-04 10:11:09-0600 [-] WebStatus using (/path/to/buildbot/public_html)
2011-12-04 10:11:09-0600 [-] removing 0 old schedulers, updating 0, and adding 0
2011-12-04 10:11:09-0600 [-] adding 1 new changesources, removing 1
2011-12-04 10:11:09-0600 [-] gitpoller: using workdir '/path/to/buildbot/gitpoller-workdir'
2011-12-04 10:11:09-0600 [-] GitPoller repository already exists
2011-12-04 10:11:09-0600 [-] configuration update complete

Reconfiguration appears to have completed successfully.

The important lines are the ones telling you that the new configuration is being loaded (at the top) and that the update is complete (at the bottom).

Now, if you go back to the waterfall page, you will see that the project’s name is whatever you may have changed it to, and when you click on the URL of the project name at the bottom of the page, it should take you to the link you put in the configuration.

1.2.4. Configuration Errors

It is very common to make a mistake when configuring buildbot, so you might as well see now what happens in that case and what you can do to fix the error.

Open up the config again and introduce a syntax error by removing the first single quote in the two lines you changed before, so they read:

c[title'] = "Hello World CI"
c[titleURL'] = "https://buildbot.github.io/hello-world/"

This creates a Python SyntaxError. Now go ahead and reconfig the master:

buildbot reconfig master

This time, the output looks like:

2015-08-14 18:40:46+0000 [-] beginning configuration update
2015-08-14 18:40:46+0000 [-] Loading configuration from '/data/buildbot/master/master.cfg'
2015-08-14 18:40:46+0000 [-] error while parsing config file:
        Traceback (most recent call last):
          File "/usr/local/lib/python2.7/dist-packages/buildbot/master.py", line 265, in reconfig
            d = self.doReconfig()
          File "/usr/local/lib/python2.7/dist-packages/twisted/internet/defer.py", line 1274, in unwindGenerator
            return _inlineCallbacks(None, gen, Deferred())
          File "/usr/local/lib/python2.7/dist-packages/twisted/internet/defer.py", line 1128, in _inlineCallbacks
            result = g.send(result)
          File "/usr/local/lib/python2.7/dist-packages/buildbot/master.py", line 289, in doReconfig
            self.configFileName)
        --- <exception caught here> ---
          File "/usr/local/lib/python2.7/dist-packages/buildbot/config.py", line 156, in loadConfig
            exec f in localDict
        exceptions.SyntaxError: EOL while scanning string literal (master.cfg, line 103)

2015-08-14 18:40:46+0000 [-] error while parsing config file: EOL while scanning string literal (master.cfg, line 103) (traceback in logfile)
2015-08-14 18:40:46+0000 [-] reconfig aborted without making any changes

Reconfiguration failed. Please inspect the master.cfg file for errors,
correct them, then try 'buildbot reconfig' again.

This time, it’s clear that there was a mistake in the configuration. Luckily, the Buildbot master will ignore the wrong configuration and keep running with the previous configuration.

The message is clear enough, so open the configuration again, fix the error, and reconfig the master.

1.2.5. Enabling the IRC Bot

Buildbot includes an IRC bot that you can tell to join a channel to control and report on the status of buildbot.

Note

Security Note

Please note that any user having access to your IRC channel, or can send a private message to the bot, will be able to create or stop builds bug #3377.

First, start an IRC client of your choice, connect to irc.freenode.net and join an empty channel. In this example we will use #buildbot-test, so go join that channel. (Note: please do not join the main buildbot channel!)

Edit master.cfg and look for the BUILDBOT SERVICES section. At the end of that section add the lines:

c['services'].append(reporters.IRC(host="irc.freenode.net", nick="bbtest",
                                   channels=["#buildbot-test"]))

The reconfigure the master and type:

grep -i irc master/twistd.log

The log output should contain a line like this:

2016-11-13 15:53:06+0100 [-] Starting factory <...>
2016-11-13 15:53:19+0100 [IrcStatusBot,client] <...>: I have joined #buildbot-test

You should see the bot now joining in your IRC client. In your IRC channel, type:

bbtest: commands

to get a list of the commands the bot supports.

Let’s tell the bot to notify on certain events. To learn on which EVENTS we can notify, type:

bbtest: help notify

Now, let’s set some event notifications:

<@lsblakk> bbtest: notify on started finished failure
< bbtest> The following events are being notified: ['started', 'failure', 'finished']

Now, go back to the web interface and force another build. Alternatively, ask the bot to force a build:

<@lsblakk> bbtest: force build --codebase= runtests
< bbtest> build #1 of runtests started
< bbtest> Hey! build runtests #1 is complete: Success [finished]

You can also see the new builds in the web interface.

a successful test run from IRC happened.

The full documentation is available at IRC.

1.2.6. Setting Authorized Web Users

The default configuration allows everyone to perform any task, like creating or stopping builds via the web interface. To restrict this to a user, look for:

c['www'] = {
    "port": 8010,
    "plugins": {
        "waterfall_view": {},
        "console_view": {}
    }
}

and append:

c['www']['authz'] = util.Authz(
        allowRules = [
            util.AnyEndpointMatcher(role="admins")
        ],
        roleMatchers = [
            util.RolesFromUsername(roles=['admins'], usernames=['Alice'])
        ]
)
c['www']['auth'] = util.UserPasswordAuth([('Alice','Password1')])

For more details, see Authentication plugins.

1.2.7. Adding a ‘try’ scheduler

Buildbot includes a way for developers to submit patches for testing without committing them to the source code control system. (This is really handy for projects that support several operating systems or architectures.)

To set this up, add the following lines to master.cfg:

from buildbot.scheduler import Try_Userpass
c['schedulers'] = []
c['schedulers'].append(Try_Userpass(
                                    name='try',
                                    builderNames=['runtests'],
                                    port=5555,
                                    userpass=[('sampleuser','samplepass')]))

Then you can submit changes using the try command.

Let’s try this out by making a one-line change to hello-world, say, to make it trace the tree by default:

git clone https://github.com/buildbot/hello-world.git hello-world-git
cd hello-world-git/hello
$EDITOR __init__.py
# change 'return "hello " + who' on line 6 to 'return "greets " + who'

Then run buildbot’s try command as follows:

cd ~/buildbot-test/master
source sandbox/bin/activate
buildbot try --connect=pb --master=127.0.0.1:5555 \
    --username=sampleuser --passwd=samplepass --vc=git

This will do git diff for you and send the resulting patch to the server for build and test against the latest sources from Git.

Now go back to the waterfall page, click on the runtests link, and scroll down. You should see that another build has been started with your change (and stdout for the tests should be chock-full of parse trees as a result). The “Reason” for the job will be listed as “‘try’ job”, and the blamelist will be empty.

To make yourself show up as the author of the change, use the --who=emailaddr option on buildbot try to pass your email address.

To make a description of the change show up, use the --properties=comment="this is a comment" option on buildbot try.

To use ssh instead of a private username/password database, see Try_Jobdir.

1.3. First Buildbot run with Docker

Note

Docker can be tricky to get working correctly if you haven’t used it before. If you’re having trouble, first determine whether it is a Buildbot issue or a Docker issue by running:

docker run ubuntu:20.04 apt-get update

If that fails, look for help with your Docker install. On the other hand, if that succeeds, then you may have better luck getting help from members of the Buildbot community.

Docker is a tool that makes building and deploying custom environments a breeze. It uses lightweight linux containers (LXC) and performs quickly, making it a great instrument for the testing community. The next section includes a Docker pre-flight check. If it takes more that 3 minutes to get the ‘Success’ message for you, try the Buildbot pip-based first run instead.

1.3.1. Current Docker dependencies

Linux system, with at least kernel 3.8 and AUFS support. For example, Standard Ubuntu, Debian and Arch systems.
Packages: lxc, iptables, ca-certificates, and bzip2 packages.
Local clock on time or slightly in the future for proper SSL communication.
This tutorial uses docker-compose to run a master, a worker, and a postgresql database server

1.3.2. Installation

Use the Docker installation instructions for your operating system.
Make sure you install docker-compose. As root or inside a virtualenv, run:
```
pip install docker-compose
```

Test docker is happy in your environment:

sudo docker run -i busybox /bin/echo Success

1.3.3. Building and running Buildbot

# clone the example repository
git clone --depth 1 https://github.com/buildbot/buildbot-docker-example-config

# Build the Buildbot container (it will take a few minutes to download packages)
cd buildbot-docker-example-config/simple
docker-compose up

You should now be able to go to http://localhost:8010 and see a web page similar to:

Click on “Builds” at the left to open the submenu and then Builders to see that the worker you just started has connected to the master:

1.3.4. Overview of the docker-compose configuration

This docker-compose configuration is made as a basis for what you would put in production

Separated containers for each component
A solid database backend with postgresql
A buildbot master that exposes its configuration to the docker host
A buildbot worker that can be cloned in order to add additional power
Containers are linked together so that the only port exposed to external is the web server
The default master container is based on Alpine linux for minimal footprint
The default worker container is based on more widely known Ubuntu distribution, as this is the container you want to customize.
Download the config from a tarball accessible via a web server

1.3.5. Playing with your Buildbot containers

If you’ve come this far, you have a Buildbot environment that you can freely experiment with.

In order to modify the configuration, you need to fork the project on github https://github.com/buildbot/buildbot-docker-example-config Then you can clone your own fork, and start the docker-compose again.

To modify your config, edit the master.cfg file, commit your changes, and push to your fork. You can use the command buildbot check-config in order to make sure the config is valid before the push. You will need to change docker-compose.yml the variable BUILDBOT_CONFIG_URL in order to point to your github fork.

The BUILDBOT_CONFIG_URL may point to a .tar.gz file accessible from HTTP. Several git servers like github can generate that tarball automatically from the master branch of a git repository If the BUILDBOT_CONFIG_URL does not end with .tar.gz, it is considered to be the URL to a master.cfg file accessible from HTTP.

1.3.6. Customize your Worker container

It is advised to customize you worker container in order to suit your project’s build dependencies and need. An example DockerFile is available which the buildbot community uses for its own CI purposes:

https://github.com/buildbot/metabbotcfg/blob/nine/docker/metaworker/Dockerfile

1.3.7. Multi-master

A multi-master environment can be setup using the multimaster/docker-compose.yml file in the example repository

# Build the Buildbot container (it will take a few minutes to download packages)
cd buildbot-docker-example-config/simple
docker-compose up -d
docker-compose scale buildbot=4

1.3.8. Going forward

1.4. Further Reading

See the following user-contributed tutorials for other highlights and ideas:

1.4.1. Buildbot in 5 minutes - a user-contributed tutorial

(Ok, maybe 10.)

Buildbot is really an excellent piece of software, however it can be a bit confusing for a newcomer (like me when I first started looking at it). Typically, at first sight, it looks like a bunch of complicated concepts that make no sense and whose relationships with each other are unclear. After some time and some reread, it all slowly starts to be more and more meaningful, until you finally say “oh!” and things start to make sense. Once you get there, you realize that the documentation is great, but only if you already know what it’s about.

This is what happened to me, at least. Here, I’m going to (try to) explain things in a way that would have helped me more as a newcomer. The approach I’m taking is more or less the reverse of that used by the documentation. That is, I’m going to start from the components that do the actual work (the builders) and go up the chain to the change sources. I hope purists will forgive this unorthodoxy. Here I’m trying to only clarify the concepts and not go into the details of each object or property; the documentation explains those quite well.

1.4.1.1. Installation

I won’t cover the installation; both Buildbot master and worker are available as packages for the major distributions, and in any case the instructions in the official documentation are fine. This document will refer to Buildbot 0.8.5 which was current at the time of writing, but hopefully the concepts are not too different in future versions. All the code shown is of course python code, and has to be included in the master.cfg configuration file.

We won’t cover basic things such as how to define the workers, project names, or other administrative information that is contained in that file; for that, again the official documentation is fine.

1.4.1.2. Builders: the workhorses

Since Buildbot is a tool whose goal is the automation of software builds, it makes sense to me to start from where we tell Buildbot how to build our software: the builder (or builders, since there can be more than one).

Simply put, a builder is an element that is in charge of performing some action or sequence of actions, normally something related to building software (for example, checking out the source, or make all), but it can also run arbitrary commands.

A builder is configured with a list of workers that it can use to carry out its task. The other fundamental piece of information that a builder needs is, of course, the list of things it has to do (which will normally run on the chosen worker). In Buildbot, this list of things is represented as a BuildFactory object, which is essentially a sequence of steps, each one defining a certain operation or command.

Enough talk, let’s see an example. For this example, we are going to assume that our super software project can be built using a simple make all, and there is another target make packages that creates rpm, deb and tgz packages of the binaries. In the real world things are usually more complex (for example there may be a configure step, or multiple targets), but the concepts are the same; it will just be a matter of adding more steps to a builder, or creating multiple builders, although sometimes the resulting builders can be quite complex.

So to perform a manual build of our project, we would type the following on the command line (assuming we are at the root of the local copy of the repository):

$ make clean    # clean remnants of previous builds
...
$ svn update
...
$ make all
...
$ make packages
...
# optional but included in the example: copy packages to some central machine
$ scp packages/*.rpm packages/*.deb packages/*.tgz someuser@somehost:/repository
...

Here we’re assuming the repository is SVN, but again the concepts are the same with git, mercurial or any other VCS.

Now, to automate this, we create a builder where each step is one of the commands we typed above. A step can be a shell command object, or a dedicated object that checks out the source code (there are various types for different repositories, see the docs for more info), or yet something else:

from buildbot.plugins import steps, util

# first, let's create the individual step objects

# step 1: make clean; this fails if the worker has no local copy, but
# is harmless and will only happen the first time
makeclean = steps.ShellCommand(name="make clean",
                               command=["make", "clean"],
                               description="make clean")

# step 2: svn update (here updates trunk, see the docs for more
# on how to update a branch, or make it more generic).
checkout = steps.SVN(baseURL='svn://myrepo/projects/coolproject/trunk',
                     mode="update",
                     username="foo",
                     password="bar",
                     haltOnFailure=True)

# step 3: make all
makeall = steps.ShellCommand(name="make all",
                             command=["make", "all"],
                             haltOnFailure=True,
                             description="make all")

# step 4: make packages
makepackages = steps.ShellCommand(name="make packages",
                                  command=["make", "packages"],
                                  haltOnFailure=True,
                                  description="make packages")

# step 5: upload packages to central server. This needs passwordless ssh
# from the worker to the server (set it up in advance as part of the worker setup)
uploadpackages = steps.ShellCommand(
    name="upload packages",
    description="upload packages",
    command="scp packages/*.rpm packages/*.deb packages/*.tgz someuser@somehost:/repository",
    haltOnFailure=True)

# create the build factory and add the steps to it
f_simplebuild = util.BuildFactory()
f_simplebuild.addStep(makeclean)
f_simplebuild.addStep(checkout)
f_simplebuild.addStep(makeall)
f_simplebuild.addStep(makepackages)
f_simplebuild.addStep(uploadpackages)

# finally, declare the list of builders. In this case, we only have one builder
c['builders'] = [
    util.BuilderConfig(name="simplebuild", workernames=['worker1', 'worker2', 'worker3'],
                       factory=f_simplebuild)
]

So our builder is called simplebuild and can run on either of worker1, worker2 or worker3. If our repository has other branches besides trunk, we could create another one or more builders to build them; in this example, only the checkout step would be different, in that it would need to check out the specific branch. Depending on how exactly those branches have to be built, the shell commands may be recycled, or new ones would have to be created if they are different in the branch. You get the idea. The important thing is that all the builders be named differently and all be added to the c['builders'] value (as can be seen above, it is a list of BuilderConfig objects).

Of course the type and number of steps will vary depending on the goal; for example, to just check that a commit doesn’t break the build, we could include just up to the make all step. Or we could have a builder that performs a more thorough test by also doing make test or other targets. You get the idea. Note that at each step except the very first we use haltOnFailure=True because it would not make sense to execute a step if the previous one failed (ok, it wouldn’t be needed for the last step, but it’s harmless and protects us if one day we add another step after it).

1.4.1.3. Schedulers

Now this is all nice and dandy, but who tells the builder (or builders) to run, and when? This is the job of the scheduler which is a fancy name for an element that waits for some event to happen, and when it does, based on that information, decides whether and when to run a builder (and which one or ones). There can be more than one scheduler. I’m being purposely vague here because the possibilities are almost endless and highly dependent on the actual setup, build purposes, source repository layout and other elements.

So a scheduler needs to be configured with two main pieces of information: on one hand, which events to react to, and on the other hand, which builder or builders to trigger when those events are detected. (It’s more complex than that, but if you understand this, you can get the rest of the details from the docs).

A simple type of scheduler may be a periodic scheduler that runs a certain builder (or builders) when a configurable amount of time has passed. In our example, that’s how we would trigger a build every hour:

from buildbot.plugins import schedulers

# define the periodic scheduler
hourlyscheduler = schedulers.Periodic(name="hourly",
                                      builderNames=["simplebuild"],
                                      periodicBuildTimer=3600)

# define the available schedulers
c['schedulers'] = [hourlyscheduler]

That’s it. Every hour this hourly scheduler will run the simplebuild builder. If we have more than one builder that we want to run every hour, we can just add them to the builderNames list when defining the scheduler. Or since multiple schedulers are allowed, other schedulers can be defined and added to c['schedulers'] in the same way.

Other types of schedulers exist; in particular, there are schedulers that can be more dynamic than the periodic one. The typical dynamic scheduler is one that learns about changes in a source repository (generally because some developer checks in some change) and triggers one or more builders in response to those changes. Let’s assume for now that the scheduler “magically” learns about changes in the repository (more about this later); here’s how we would define it:

from buildbot.plugins import schedulers

# define the dynamic scheduler
trunkchanged = schedulers.SingleBranchScheduler(name="trunkchanged",
                                                change_filter=util.ChangeFilter(branch=None),
                                                treeStableTimer=300,
                                                builderNames=["simplebuild"])

# define the available schedulers
c['schedulers'] = [trunkchanged]

This scheduler receives changes happening to the repository, and among all of them, pays attention to those happening in “trunk” (that’s what branch=None means). In other words, it filters the changes to react only to those it’s interested in. When such changes are detected, and the tree has been quiet for 5 minutes (300 seconds), it runs the simplebuild builder. The treeStableTimer helps in those situations where commits tend to happen in bursts, which would otherwise result in multiple build requests queuing up.

What if we want to act on two branches (say, trunk and 7.2)? First, we create two builders, one for each branch, and then we create two dynamic schedulers:

from buildbot.plugins import schedulers

# define the dynamic scheduler for trunk
trunkchanged = schedulers.SingleBranchScheduler(name="trunkchanged",
                                                change_filter=util.ChangeFilter(branch=None),
                                                treeStableTimer=300,
                                                builderNames=["simplebuild-trunk"])

# define the dynamic scheduler for the 7.2 branch
branch72changed = schedulers.SingleBranchScheduler(
    name="branch72changed",
    change_filter=util.ChangeFilter(branch='branches/7.2'),
    treeStableTimer=300,
    builderNames=["simplebuild-72"])

# define the available schedulers
c['schedulers'] = [trunkchanged, branch72changed]

The syntax of the change filter is VCS-dependent (above is for SVN), but again, once the idea is clear, the documentation has all the details. Another feature of the scheduler is that it can be told which changes, within those it’s paying attention to, are important and which are not. For example, there may be a documentation directory in the branch the scheduler is watching, but changes under that directory should not trigger a build of the binary. This finer filtering is implemented by means of the fileIsImportant argument to the scheduler (full details in the docs and - alas - in the sources).

1.4.1.4. Change sources

Earlier, we said that a dynamic scheduler “magically” learns about changes; the final piece of the puzzle is change sources, which are precisely the elements in Buildbot whose task is to detect changes in a repository and communicate them to the schedulers. Note that periodic schedulers don’t need a change source since they only depend on elapsed time; dynamic schedulers, on the other hand, do need a change source.

A change source is generally configured with information about a source repository (which is where changes happen). A change source can watch changes at different levels in the hierarchy of the repository, so for example, it is possible to watch the whole repository or a subset of it, or just a single branch. This determines the extent of the information that is passed down to the schedulers.

There are many ways a change source can learn about changes; it can periodically poll the repository for changes, or the VCS can be configured (for example through hook scripts triggered by commits) to push changes into the change source. While these two methods are probably the most common, they are not the only possibilities. It is possible, for example, to have a change source detect changes by parsing an email sent to a mailing list when a commit happens. Yet other methods exist and the manual again has the details.

To complete our example, here’s a change source that polls a SVN repository every 2 minutes:

from buildbot.plugins import changes, util

svnpoller = changes.SVNPoller(repourl="svn://myrepo/projects/coolproject",
                              svnuser="foo",
                              svnpasswd="bar",
                              pollInterval=120,
                              split_file=util.svn.split_file_branches)

c['change_source'] = svnpoller

This poller watches the whole “coolproject” section of the repository, so it will detect changes in all the branches. We could have said:

repourl = "svn://myrepo/projects/coolproject/trunk"

or:

repourl = "svn://myrepo/projects/coolproject/branches/7.2"

to watch only a specific branch.

To watch another project, you need to create another change source, and you need to filter changes by project. For instance, when you add a change source watching project ‘superproject’ to the above example, you need to change the original scheduler from:

trunkchanged = schedulers.SingleBranchScheduler(
    name="trunkchanged",
    change_filter=filter.ChangeFilter(branch=None),
    # ...
    )

to e.g.:

trunkchanged = schedulers.SingleBranchScheduler(
    name="trunkchanged",
    change_filter=filter.ChangeFilter(project="coolproject", branch=None),
    # ...
    )

otherwise, coolproject will be built when there’s a change in superproject.

Since we’re watching more than one branch, we need a method to tell in which branch the change occurred when we detect one. This is what the split_file argument does, it takes a callable that Buildbot will call to do the job. The split_file_branches function, which comes with Buildbot, is designed for exactly this purpose so that’s what the example above uses.

And of course this is all SVN-specific, but there are pollers for all the popular VCSs.

Note that if you have many projects, branches, and builders, it probably pays not to hardcode all the schedulers and builders in the configuration, but generate them dynamically starting from the list of all projects, branches, targets, etc, and using loops to generate all possible combinations (or only the needed ones, depending on the specific setup), as explained in the documentation chapter about Customization.

1.4.1.5. Reporters

Now that the basics are in place, let’s go back to the builders, which is where the real work happens. Reporters are simply the means Buildbot uses to inform the world about what’s happening, that is, how builders are doing. There are many reporters: a mail notifier, an IRC notifier, and others. They are described fairly well in the manual.

One thing I’ve found useful is the ability to pass a domain name as the lookup argument to a mailNotifier, which allows you to take an unqualified username as it appears in the SVN change and create a valid email address by appending the given domain name to it:

from buildbot.plugins import reporter

# if jsmith commits a change, an email for the build is sent to jsmith@example.org
notifier = reporter.MailNotifier(fromaddr="buildbot@example.org",
                               sendToInterestedUsers=True,
                               lookup="example.org")
c['reporters'].append(notifier)

The mail notifier can be customized at will by means of the messageFormatter argument, which is a class that Buildbot calls to format the body of the email, and to which it makes available lots of information about the build. For more details, look into the Reporters section of the Buildbot manual.

1.4.1.6. Conclusion

Please note that this article has just scratched the surface; given the complexity of the task of build automation, the possibilities are almost endless. So there’s much much more to say about Buildbot. Hopefully this has been a gentle introduction before reading the official manual. Had I found an explanation as the one above when I was approaching Buildbot, I’d have had to read the manual just once, rather than multiple times. I hope this can help someone else.

(Thanks to Davide Brini for permission to include this tutorial, derived from one he originally posted at http://backreference.org .)

This is the Buildbot manual for Buildbot version 4.0.4.

2. Buildbot Manual

2.1. Introduction

Buildbot is a framework to automate the compile and test cycle that is used to validate code changes in most software projects.

Features:

run builds on a variety of worker platforms
arbitrary build process: handles projects using C, Python, whatever
minimal host requirements: Python and Twisted
workers can be behind a firewall if they can still do checkout
status delivery through web page, email, IRC, other protocols
flexible configuration by subclassing generic build process classes
debug tools to force a new build, submit fake Changes, query worker status
released under the GPL

2.1.1. System Architecture

Buildbot consists of a single buildmaster and one or more workers that connect to the master. The buildmaster makes all decisions about what, when, and how to build. The workers only connect to master and execute whatever commands they are instructed to execute.

The usual flow of information is as follows:

the buildmaster fetches new code changes from version control systems

the buildmaster decides what builds (if any) to start

the builds are performed by executing commands on the workers (e.g. git clone, make, make check).

the workers send the results of the commands back to the buildmaster

buildmaster interprets the results of the commands and marks the builds as successful or failing

buildmaster sends success or failure reports to external services to e.g. inform the developers.

2.1.1.1. Worker Connections

The workers connect to the buildmaster over a TCP connection to a publicly-visible port. This allows workers to live behind a NAT or similar firewalls as long as they can get to buildmaster. After the connection is established, the connection is bidirectional: commands flow from the buildmaster to the worker and results flow from the worker to the buildmaster.

The buildmaster does not provide the workers with the source code itself, only with commands necessary to perform the source code checkout. As a result, the workers need to be able to reach the source code repositories that they are supposed to build.

2.1.1.2. Buildmaster Architecture

The following is rough overview of the data flow within the buildmaster.

The following provides a short overview of the core components of Buildbot master. For a more detailed description see the Concepts page.

The core components of Buildbot master are as follows:

Builders: A builder is a user-configurable description of how to perform a build. It defines what steps a new build will have, what workers it may run on and a couple of other properties. A builder takes a build request which specifies the intention to create a build for specific versions of code and produces a build which is a concrete description of a build including a list of steps to perform, the worker this needs to be performed on and so on.
Schedulers:: A scheduler is a user-configurable component that decides when to start a build. The decision could be based on time, on new code being committed or on similar events.
Change Sources:: Change sources are user-configurable components that interact with external version control systems and retrieve new code. Internally new code is represented as Changes which roughly correspond to single commit or changeset. The design of Buildbot requires the workers to have their own copies of the source code, thus change sources is an optional component as long as there are no schedulers that create new builds based on new code commit events.
Reporters: Reporters are user-configurable components that send information about started or completed builds to external sources. Buildbot provides its own web application to observe this data, so reporters are optional. However they can be used to provide up to date build status on platforms such as GitHub or sending emails.

2.2. Installation

2.2.1. Buildbot Components

Buildbot is shipped in two components: the buildmaster (called buildbot for legacy reasons) and the worker. The worker component has far fewer requirements, and is more broadly compatible than the buildmaster. You will need to carefully pick the environment in which to run your buildmaster, but the worker should be able to run just about anywhere.

It is possible to install the buildmaster and worker on the same system, although for anything but the smallest installation this arrangement will not be very efficient.

2.2.2. Requirements

2.2.2.1. Common Requirements

At a bare minimum, you’ll need the following for both the buildmaster and a worker:

Python: https://www.python.org

Buildbot master works with Python-3.6+. Buildbot worker works with Python 2.7, or Python 3.5+.

Note

This should be a “normal” build of Python. Builds of Python with debugging enabled or other unusual build parameters are likely to cause incorrect behavior.

Twisted: http://twistedmatrix.com

Buildbot requires Twisted-17.9.0 or later on the master and the worker. In upcoming versions of Buildbot, a newer Twisted will also be required on the worker. As always, the most recent version is recommended.

Certifi: https://github.com/certifi/python-certifi

Certifi provides collection of Root Certificates for validating the trustworthiness of SSL certificates. Unfortunately it does not support any addition of own company certificates. At the moment you need to add your own .PEM content to cacert.pem manually.

Of course, your project’s build process will impose additional requirements on the workers. These hosts must have all the tools necessary to compile and test your project’s source code.

Note

If your internet connection is secured by a proxy server, please check your http_proxy and https_proxy environment variables. Otherwise pip and other tools will fail to work.

Windows Support

Buildbot - both master and worker - runs well natively on Windows. The worker runs well on Cygwin, but because of problems with SQLite on Cygwin, the master does not.

Buildbot’s windows testing is limited to the most recent Twisted and Python versions. For best results, use the most recent available versions of these libraries on Windows.

Pywin32: http://sourceforge.net/projects/pywin32/

Twisted requires PyWin32 in order to spawn processes on Windows.

Build Tools for Visual Studio 2019 - Microsoft Visual C++ compiler

Twisted requires MSVC to compile some parts like tls during the installation, see https://twistedmatrix.com/trac/wiki/WindowsBuilds and https://wiki.python.org/moin/WindowsCompilers.

2.2.2.2. Buildmaster Requirements

Note that all of these requirements aside from SQLite can easily be installed from the Python package repository, PyPI.

sqlite3: http://www.sqlite.org

Buildbot requires a database to store its state, and by default uses SQLite. Version 3.7.0 or higher is recommended, although Buildbot will run down to 3.6.16 – at the risk of “Database is locked” errors. The minimum version is 3.4.0, below which parallel database queries and schema introspection fail.

Please note that Python ships with sqlite3 by default.

If you configure a different database engine, then SQLite is not required. however note that Buildbot’s own unit tests require SQLite.

Jinja2: http://jinja.pocoo.org/

Buildbot requires Jinja version 2.1 or higher.

Jinja2 is a general purpose templating language and is used by Buildbot to generate the HTML output.

SQLAlchemy: http://www.sqlalchemy.org/

Buildbot requires SQLAlchemy version 1.4.0 or higher. SQLAlchemy allows Buildbot to build database schemas and queries for a wide variety of database systems.

Alembic: https://alembic.sqlalchemy.org/en/latest/

Buildbot requires Alembic version 1.6.0 or higher. Buildbot uses Alembic to manage schema upgrades from version to version.

Python-Dateutil: http://labix.org/python-dateutil

Buildbot requires Python-Dateutil in version 1.5 or higher (the last version to support Python-2.x). This is a small, pure-Python library.

Autobahn:

The master requires Autobahn version 0.16.0 or higher with Python 2.7.

txrequests: https://github.com/tardyp/txrequests or treq: https://github.com/twisted/treq

Both libraries are optional, but a lot of Buildbot plugins assume that one of it is installed. Otherwise plugins will complain in the twisted log file if it is not installed. Here is a little comparison table:

txrequests

treq

International Domains and URLs

yes

yes

Keep-Alive & Connection Pooling

yes

yes

Sessions with Cookie Persistence

yes

yes

Browser-style SSL Verification

yes

yes

Basic Authentication

yes

yes

Digest Authentication

yes

no

Elegant Key/Value Cookies

yes

yes

Automatic Decompression

yes

yes

Unicode Response Bodies

yes

yes

Multi-part File Uploads

yes

yes

Connection Timeouts

yes

yes

HTTP(S) Proxy Support

yes

no

.netrc support

yes

no

Python 2.7

yes

yes

Python 3.x

yes

yes

Speed

slower

fast

2.2.3. Installing the code

2.2.3.1. The Buildbot Packages

Buildbot comes in several parts: buildbot (the buildmaster), buildbot-worker (the worker), buildbot-www, and several web plugins such as buildbot-waterfall-view.

The worker and buildmaster can be installed individually or together. The base web (buildbot.www) and web plugins are required to run a master with a web interface (the common configuration).

2.2.3.2. Installation From PyPI

The preferred way to install Buildbot is using pip. For the master:

pip install buildbot

and for the worker:

pip install buildbot-worker

When using pip to install, instead of distribution specific package managers, e.g. via apt or ports, it is simpler to choose exactly which version one wants to use. It may however be easier to install via distribution specific package managers, but note that they may provide an earlier version than what is available via pip.

If you plan to use TLS or SSL in master configuration (e.g. to fetch resources over HTTPS using twisted.web.client), you need to install Buildbot with tls extras:

pip install buildbot[tls]

2.2.3.3. Installation From Tarballs

Use pip to install buildbot master or buildbot-worker using tarball.

Note

Support for installation using setup.py has been discontinued due to the deprecation of support in the distutils and setuptools packages. For more details, see Why you shouldn’t invoke setup.py directly.

If you have a tarball file named buildbot.tar.gz in your current directory, you can install it using:

pip install buildbot.tar.gz

Alternatively, you can provide a URL if the tarball is hosted online. Make sure to replace the URL with the actual URL of tarball you want to install.

pip install https://github.com/buildbot/buildbot/releases/download/v3.10.1/buildbot-3.10.1.tar.gz

Installation may need to be done as root. This will put the bulk of the code in somewhere like /usr/lib/pythonx.y/site-packages/buildbot. It will also install the buildbot command-line tool in /usr/bin/buildbot.

If the environment variable $NO_INSTALL_REQS is set to 1, then setup.py will not try to install Buildbot’s requirements. This is usually only useful when building a Buildbot package.

To test this, shift to a different directory (like /tmp), and run:

buildbot --version
# or
buildbot-worker --version

If it shows you the versions of Buildbot and Twisted, the install went ok. If it says “no such command” or gets an ImportError when it tries to load the libraries, then something went wrong. pydoc buildbot is another useful diagnostic tool.

Windows users will find these files in other places. You will need to make sure that Python can find the libraries, and will probably find it convenient to have buildbot in your PATH.

2.2.3.4. Installation in a Virtualenv

If you cannot or do not wish to install buildbot into a site-wide location like /usr or /usr/local, you can also install it into the account’s home directory or any other location using a tool like virtualenv.

2.2.3.5. Running Buildbot’s Tests (optional)

If you wish, you can run the buildbot unit test suite. First, ensure that you have the mock Python module installed from PyPI. You must not be using a Python wheels packaged version of Buildbot or have specified the bdist_wheel command when building. The test suite is not included with the PyPi packaged version. This module is not required for ordinary Buildbot operation - only to run the tests. Note that this is not the same as the Fedora mock package!

You can check if you have mock with:

python -mmock

Then, run the tests:

PYTHONPATH=. trial buildbot.test
# or
PYTHONPATH=. trial buildbot_worker.test

Nothing should fail, although a few might be skipped.

If any of the tests fail for reasons other than a missing mock, you should stop and investigate the cause before continuing the installation process, as it will probably be easier to track down the bug early. In most cases, the problem is incorrectly installed Python modules or a badly configured PYTHONPATH. This may be a good time to contact the Buildbot developers for help.

2.2.4. Buildmaster Setup

2.2.4.1. Creating a buildmaster

As you learned earlier (System Architecture), the buildmaster runs on a central host (usually one that is publicly visible, so everybody can check on the status of the project), and controls all aspects of the buildbot system

You will probably wish to create a separate user account for the buildmaster, perhaps named buildmaster. Do not run the buildmaster as root!

You need to choose a directory for the buildmaster, called the basedir. This directory will be owned by the buildmaster. It will contain the configuration, database, and status information - including logfiles. On a large buildmaster this directory will see a lot of activity, so it should be on a disk with adequate space and speed.

Once you’ve picked a directory, use the buildbot create-master command to create the directory and populate it with startup files:

buildbot create-master -r basedir

You will need to create a configuration file before starting the buildmaster. Most of the rest of this manual is dedicated to explaining how to do this. A sample configuration file is placed in the working directory, named master.cfg.sample, which can be copied to master.cfg and edited to suit your purposes.

(Internal details: This command creates a file named buildbot.tac that contains all the state necessary to create the buildmaster. Twisted has a tool called twistd which can use this .tac file to create and launch a buildmaster instance. Twistd takes care of logging and daemonization (running the program in the background). /usr/bin/buildbot is a front end which runs twistd for you.)

Your master will need a database to store the various information about your builds, and its configuration. By default, the sqlite3 backend will be used. This needs no configuration, neither extra software. All information will be stored in the file state.sqlite. Buildbot however supports multiple backends. See Using A Database Server for more options.

Buildmaster Options

This section lists options to the create-master command. You can also type buildbot create-master --help for an up-to-the-moment summary.

--force: This option will allow to re-use an existing directory.

--no-logrotate: This disables internal worker log management mechanism. With this option worker does not override the default logfile name and its behaviour giving a possibility to control those with command-line options of twistd daemon.

--relocatable: This creates a “relocatable” buildbot.tac, which uses relative paths instead of absolute paths, so that the buildmaster directory can be moved about.

--config: The name of the configuration file to use. This configuration file need not reside in the buildmaster directory.

--log-size: This is the size in bytes when exceeded to rotate the Twisted log files. The default is 10MiB.

--log-count: This is the number of log rotations to keep around. You can either specify a number or None to keep all twistd.log files around. The default is 10.

--db: The database that the Buildmaster should use. Note that the same value must be added to the configuration file.

2.2.5. Worker Setup

2.2.5.1. Creating a worker

Typically, you will be adding a worker to an existing buildmaster, to provide additional architecture coverage. The Buildbot administrator will give you several pieces of information necessary to connect to the buildmaster. You should also be somewhat familiar with the project being tested so that you can troubleshoot build problems locally.

Buildbot exists to make sure that the project’s stated how to build it process actually works. To this end, the worker should run in an environment just like that of your regular developers. Typically the project’s build process is documented somewhere (README, INSTALL, etc), in a document that should mention all library dependencies and contain a basic set of build instructions. This document will be useful as you configure the host and account in which worker runs.

Here’s a good checklist for setting up a worker:

Set up the account

It is recommended (although not mandatory) to set up a separate user account for the worker. This account is frequently named buildbot or worker. This serves to isolate your personal working environment from that of the worker’s, and helps to minimize the security threat posed by letting possibly-unknown contributors run arbitrary code on your system. The account should have a minimum of fancy init scripts.

Install the Buildbot code

Follow the instructions given earlier (Installing the code). If you use a separate worker account, and you didn’t install the Buildbot code to a shared location, then you will need to install it with --home=~ for each account that needs it.

Set up the host

Make sure the host can actually reach the buildmaster. Usually the buildmaster is running a status webserver on the same machine, so simply point your web browser at it and see if you can get there. Install whatever additional packages or libraries the project’s INSTALL document advises. (or not: if your worker is supposed to make sure that building without optional libraries still works, then don’t install those libraries.)

Again, these libraries don’t necessarily have to be installed to a site-wide shared location, but they must be available to your build process. Accomplishing this is usually very specific to the build process, so installing them to /usr or /usr/local is usually the best approach.

Test the build process

Follow the instructions in the INSTALL document, in the worker’s account. Perform a full CVS (or whatever) checkout, configure, make, run tests, etc. Confirm that the build works without manual fussing. If it doesn’t work when you do it manually, it will be unlikely to work when Buildbot attempts to do it in an automated fashion.

Choose a base directory

This should be somewhere in the worker’s account, typically named after the project which is being tested. The worker will not touch any file outside of this directory. Something like ~/Buildbot or ~/Workers/fooproject is appropriate.

Get the buildmaster host/port, workername, and password

When the Buildbot admin configures the buildmaster to accept and use your worker, they will provide you with the following pieces of information:

your worker’s name

the password assigned to your worker

the hostname and port number of the buildmaster

Create the worker

Now run the ‘worker’ command as follows:

buildbot-worker create-worker BASEDIR MASTERHOST:PORT WORKERNAME PASSWORD

This will create the base directory and a collection of files inside, including the buildbot.tac file that contains all the information you passed to the buildbot-worker command.

Fill in the hostinfo files

When it first connects, the worker will send a few files up to the buildmaster which describe the host that it is running on. These files are presented on the web status display so that developers have more information to reproduce any test failures that are witnessed by the Buildbot. There are sample files in the info subdirectory of the Buildbot’s base directory. You should edit these to correctly describe you and your host.

BASEDIR/info/admin should contain your name and email address. This is the worker admin address, and will be visible from the build status page (so you may wish to munge it a bit if address-harvesting spambots are a concern).

BASEDIR/info/host should be filled with a brief description of the host: OS, version, memory size, CPU speed, versions of relevant libraries installed, and finally the version of the Buildbot code which is running the worker.

The optional BASEDIR/info/access_uri can specify a URI which will connect a user to the machine. Many systems accept ssh://hostname URIs for this purpose.

If you run many workers, you may want to create a single ~worker/info file and share it among all the workers with symlinks.

Worker Options

There are a handful of options you might want to use when creating the worker with the buildbot-worker create-worker <options> DIR <params> command. You can type buildbot-worker create-worker --help for a summary. To use these, just include them on the buildbot-worker create-worker command line, like this

buildbot-worker create-worker --umask=0o22 ~/worker buildmaster.example.org:42012 \
    {myworkername} {mypasswd}

--protocol: This is a string representing a protocol to be used when creating master-worker connection. The default option is Perspective Broker (pb).

--no-logrotate: This disables internal worker log management mechanism. With this option worker does not override the default logfile name and its behaviour giving a possibility to control those with command-line options of twistd daemon.

--umask: This is a string (generally an octal representation of an integer) which will cause the worker process’ umask value to be set shortly after initialization. The twistd daemonization utility forces the umask to 077 at startup (which means that all files created by the worker or its child processes will be unreadable by any user other than the worker account). If you want build products to be readable by other accounts, you can add --umask=0o22 to tell the worker to fix the umask after twistd clobbers it. If you want build products to be writable by other accounts too, use --umask=0o000, but this is likely to be a security problem.

--keepalive

This is a number that indicates how frequently keepalive messages should be sent from the worker to the buildmaster, expressed in seconds. The default (600) causes a message to be sent to the buildmaster at least once every 10 minutes. To set this to a lower value, use e.g. --keepalive=120.

If the worker is behind a NAT box or stateful firewall, these messages may help to keep the connection alive: some NAT boxes tend to forget about a connection if it has not been used in a while. When this happens, the buildmaster will think that the worker has disappeared, and builds will time out. Meanwhile the worker will not realize that anything is wrong.

--maxdelay: This is a number that indicates the maximum amount of time the worker will wait between connection attempts, expressed in seconds. The default (300) causes the worker to wait at most 5 minutes before trying to connect to the buildmaster again.

--maxretries

This is a number that indicates the maximum number of times the worker will make connection attempts. After that amount, the worker process will stop. This option is useful for Latent Workers to avoid consuming resources in case of misconfiguration or master failure.

For VM based latent workers, the user is responsible for halting the system when the Buildbot worker has exited. This feature is heavily OS dependent, and cannot be managed by the Buildbot worker. For example, with systemd, one can add ExecStopPost=shutdown now to the Buildbot worker service unit configuration.

--log-size: This is the size in bytes when exceeded to rotate the Twisted log files.

--log-count: This is the number of log rotations to keep around. You can either specify a number or None to keep all twistd.log files around. The default is 10.

--allow-shutdown

Can also be passed directly to the worker constructor in buildbot.tac. If set, it allows the worker to initiate a graceful shutdown, meaning that it will ask the master to shut down the worker when the current build, if any, is complete.

Setting allow_shutdown to file will cause the worker to watch shutdown.stamp in basedir for updates to its mtime. When the mtime changes, the worker will request a graceful shutdown from the master. The file does not need to exist prior to starting the worker.

Setting allow_shutdown to signal will set up a SIGHUP handler to start a graceful shutdown. When the signal is received, the worker will request a graceful shutdown from the master.

The default value is None, in which case this feature will be disabled.

Both master and worker must be at least version 0.8.3 for this feature to work.

--use-tls: Can also be passed directly to the Worker constructor in buildbot.tac. If set, the generated connection string starts with tls instead of with tcp, allowing encrypted connection to the buildmaster. Make sure the worker trusts the buildmasters certificate. If you have an non-authoritative certificate (CA is self-signed) see option --connection-string and also Worker-TLS-Config below.

--delete-leftover-dirs: Can also be passed directly to the Worker constructor in buildbot.tac. If set, unexpected directories in worker base directory will be removed. Otherwise, a warning will be displayed in twistd.log so that you can manually remove them.

--connection-string: Can also be passed directly to the Worker constructor in buildbot.tac. If set, the worker connection to master will be made using this connection_string. See Worker-TLS-Config below for more details. Note that this option will override required positional argument masterhost[:port] and also option --use-tls.

--proxy-connection-string: Can also be passed directly to the Worker constructor in buildbot.tac. If set, the worker connection will be tunneled through a HTTP proxy specified by the option value.

Other Worker Configuration

unicode_encoding

This represents the encoding that Buildbot should use when converting unicode commandline arguments into byte strings in order to pass to the operating system when spawning new processes.

The default value is what Python’s sys.getfilesystemencoding returns, which on Windows is ‘mbcs’, on Mac OSX is ‘utf-8’, and on Unix depends on your locale settings.

If you need a different encoding, this can be changed in your worker’s buildbot.tac file by adding a unicode_encoding argument to the Worker constructor.

s = Worker(buildmaster_host, port, workername, passwd, basedir,
           keepalive, usepty, umask=umask, maxdelay=maxdelay,
           unicode_encoding='utf-8', allow_shutdown='signal')

Worker TLS Configuration

tls

See --useTls option above as an alternative to setting the conneciton_string manually.

connection_string

For TLS connections to the master, the connection_string-argument must be passed to the worker constructor. buildmaster_host and port must then be None.

connection_string will be used to create a client endpoint with clientFromString. An example of connection_string is "TLS:buildbot-master.com:9989".

See more about how to formulate the connection string in ConnectionStrings.

Example TLS connection string:

s = Worker(None, None, workername, passwd, basedir, keepalive,
           connection_string='TLS:buildbot-master.com:9989')

Make sure the worker trusts the certificate of the master. If you have a non-authoritative certificate (CA is self-signed), the trustRoots parameter can be used.

s = Worker(None, None, workername, passwd, basedir, keepalive,
           connection_string=
           'TLS:buildbot-master.com:9989:trustRoots=/dir-with-ca-certs')

It must point to a directory with PEM-encoded certificates. For example:

$ cat /dir-with-ca-certs/ca.pem
-----BEGIN CERTIFICATE-----
MIIE9DCCA9ygAwIBAgIJALEqLrC/m1w3MA0GCSqGSIb3DQEBCwUAMIGsMQswCQYD
VQQGEwJaWjELMAkGA1UECBMCUUExEDAOBgNVBAcTB05vd2hlcmUxETAPBgNVBAoT
CEJ1aWxkYm90MRkwFwYDVQQLExBEZXZlbG9wbWVudCBUZWFtMRQwEgYDVQQDEwtC
dWlsZGJvdCBDQTEQMA4GA1UEKRMHRWFzeVJTQTEoMCYGCSqGSIb3DQEJARYZYnVp
bGRib3RAaW50ZWdyYXRpb24udGVzdDAeFw0xNjA5MDIxMjA5NTJaFw0yNjA4MzEx
MjA5NTJaMIGsMQswCQYDVQQGEwJaWjELMAkGA1UECBMCUUExEDAOBgNVBAcTB05v
d2hlcmUxETAPBgNVBAoTCEJ1aWxkYm90MRkwFwYDVQQLExBEZXZlbG9wbWVudCBU
ZWFtMRQwEgYDVQQDEwtCdWlsZGJvdCBDQTEQMA4GA1UEKRMHRWFzeVJTQTEoMCYG
CSqGSIb3DQEJARYZYnVpbGRib3RAaW50ZWdyYXRpb24udGVzdDCCASIwDQYJKoZI
hvcNAQEBBQADggEPADCCAQoCggEBALJZcC9j4XYBi1fYT/fibY2FRWn6Qh74b1Pg
I7iIde6Sf3DPdh/ogYvZAT+cIlkZdo4v326d0EkuYKcywDvho8UeET6sIYhuHPDW
lRl1Ret6ylxpbEfxFNvMoEGNhYAP0C6QS2eWEP9LkV2lCuMQtWWzdedjk+efqBjR
Gozaim0lr/5lx7bnVx0oRLAgbI5/9Ukbopansfr+Cp9CpFpbNPGZSmELzC3FPKXK
5tycj8WEqlywlha2/VRnCZfYefB3aAuQqQilLh+QHyhn6hzc26+n5B0l8QvrMkOX
atKdznMLzJWGxS7UwmDKcsolcMAW+82BZ8nUCBPF3U5PkTLO540CAwEAAaOCARUw
ggERMB0GA1UdDgQWBBT7A/I+MZ1sFFJ9jikYkn51Q3wJ+TCB4QYDVR0jBIHZMIHW
gBT7A/I+MZ1sFFJ9jikYkn51Q3wJ+aGBsqSBrzCBrDELMAkGA1UEBhMCWloxCzAJ
BgNVBAgTAlFBMRAwDgYDVQQHEwdOb3doZXJlMREwDwYDVQQKEwhCdWlsZGJvdDEZ
MBcGA1UECxMQRGV2ZWxvcG1lbnQgVGVhbTEUMBIGA1UEAxMLQnVpbGRib3QgQ0Ex
EDAOBgNVBCkTB0Vhc3lSU0ExKDAmBgkqhkiG9w0BCQEWGWJ1aWxkYm90QGludGVn
cmF0aW9uLnRlc3SCCQCxKi6wv5tcNzAMBgNVHRMEBTADAQH/MA0GCSqGSIb3DQEB
CwUAA4IBAQCJGJVMAmwZRK/mRqm9E0e3s4YGmYT2jwX5IX17XljEy+1cS4huuZW2
33CFpslkT1MN/r8IIZWilxT/lTujHyt4eERGjE1oRVKU8rlTH8WUjFzPIVu7nkte
09abqynAoec8aQukg79NRCY1l/E2/WzfnUt3yTgKPfZmzoiN0K+hH4gVlWtrizPA
LaGwoslYYTA6jHNEeMm8OQLNf17OTmAa7EpeIgVpLRCieI9S3JIG4WYU8fVkeuiU
cB439SdixU4cecVjNfFDpq6JM8N6+DQoYOSNRt9Dy0ioGyx5D4lWoIQ+BmXQENal
gw+XLyejeNTNgLOxf9pbNYMJqxhkTkoE
-----END CERTIFICATE-----

Using TCP in connection_string is the equivalent to using the buildmaster_host and port arguments.

s = Worker(None, None, workername, passwd, basedir, keepalive
           connection_string='TCP:buildbot-master.com:9989')

is equivalent to

s = Worker('buildbot-master.com', 9989, workername, passwd, basedir,
           keepalive)

2.2.6. Next Steps

2.2.6.1. Launching the daemons

Both the buildmaster and the worker run as daemon programs. To launch them, pass the working directory to the buildbot and buildbot-worker commands, as appropriate:

# start a master
buildbot start [ BASEDIR ]
# start a worker
buildbot-worker start [ WORKER_BASEDIR ]

The BASEDIR is optional and can be omitted if the current directory contains the buildbot configuration (the buildbot.tac file).

buildbot start

This command will start the daemon and then return, so normally it will not produce any output. To verify that the programs are indeed running, look for a pair of files named twistd.log and twistd.pid that should be created in the working directory. twistd.pid contains the process ID of the newly-spawned daemon.

When the worker connects to the buildmaster, new directories will start appearing in its base directory. The buildmaster tells the worker to create a directory for each Builder which will be using that worker. All build operations are performed within these directories: CVS checkouts, compiles, and tests.

Once you get everything running, you will want to arrange for the buildbot daemons to be started at boot time. One way is to use cron, by putting them in a @reboot crontab entry [1]

@reboot buildbot start [ BASEDIR ]

When you run crontab to set this up, remember to do it as the buildmaster or worker account! If you add this to your crontab when running as your regular account (or worse yet, root), then the daemon will run as the wrong user, quite possibly as one with more authority than you intended to provide.

It is important to remember that the environment provided to cron jobs and init scripts can be quite different than your normal runtime. There may be fewer environment variables specified, and the PATH may be shorter than usual. It is a good idea to test out this method of launching the worker by using a cron job with a time in the near future, with the same command, and then check twistd.log to make sure the worker actually started correctly. Common problems here are for /usr/local or ~/bin to not be on your PATH, or for PYTHONPATH to not be set correctly. Sometimes HOME is messed up too. If using systemd to launch buildbot-worker, it may be a good idea to specify a fixed PATH using the Environment directive (see systemd unit file example).

Some distributions may include conveniences to make starting buildbot at boot time easy. For instance, with the default buildbot package in Debian-based distributions, you may only need to modify /etc/default/buildbot (see also /etc/init.d/buildbot, which reads the configuration in /etc/default/buildbot).

Buildbot also comes with its own init scripts that provide support for controlling multi-worker and multi-master setups (mostly because they are based on the init script from the Debian package). With a little modification, these scripts can be used on both Debian and RHEL-based distributions. Thus, they may prove helpful to package maintainers who are working on buildbot (or to those who haven’t yet split buildbot into master and worker packages).

# install as /etc/default/buildbot-worker
#         or /etc/sysconfig/buildbot-worker
worker/contrib/init-scripts/buildbot-worker.default

# install as /etc/default/buildmaster
#         or /etc/sysconfig/buildmaster
master/contrib/init-scripts/buildmaster.default

# install as /etc/init.d/buildbot-worker
worker/contrib/init-scripts/buildbot-worker.init.sh

# install as /etc/init.d/buildmaster
master/contrib/init-scripts/buildmaster.init.sh

# ... and tell sysvinit about them
chkconfig buildmaster reset
# ... or
update-rc.d buildmaster defaults

2.2.6.2. Launching worker as Windows service

Security consideration

Setting up the buildbot worker as a Windows service requires Windows administrator rights. It is important to distinguish installation stage from service execution. It is strongly recommended run Buildbot worker with lowest required access rights. It is recommended run a service under machine local non-privileged account.

If you decide run Buildbot worker under domain account it is recommended to create dedicated strongly limited user account that will run Buildbot worker service.

Windows service setup

In this description, we assume that the buildbot worker account is the local domain account worker.

In case worker should run under domain user account please replace .\worker with <domain>\worker. Please replace <worker.passwd> with given user password. Please replace <worker.basedir> with the full/absolute directory specification to the created worker (what is called BASEDIR in Creating a worker).

buildbot_worker_windows_service --user .\worker --password <worker.passwd> --startup auto install
powershell -command "& {&'New-Item' -path Registry::HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\BuildBot\Parameters}"
powershell -command "& {&'set-ItemProperty' -path Registry::HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\BuildBot\Parameters -Name directories -Value '<worker.basedir>'}"

The first command automatically adds user rights to run Buildbot as service.

Modify environment variables

This step is optional and may depend on your needs. At least we have found useful to have dedicated temp folder worker steps. It is much easier discover what temporary files your builds leaks/misbehaves.

As Administrator run regedit
Open the key Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Buildbot.
Create a new value of type REG_MULTI_SZ called Environment.
Add entries like

TMP=c:\bbw\tmp
TEMP=c:\bbw\tmp

Check if Buildbot can start correctly configured as Windows service

As admin user run the command net start buildbot. In case everything goes well, you should see following output

The BuildBot service is starting.
The BuildBot service was started successfully.

Troubleshooting

If anything goes wrong check

Twisted log on C:\bbw\worker\twistd.log
Windows system event log (eventvwr.msc in command line, Show-EventLog in PowerShell).

2.2.6.3. Logfiles

While a buildbot daemon runs, it emits text to a logfile, named twistd.log. A command like tail -f twistd.log is useful to watch the command output as it runs.

The buildmaster will announce any errors with its configuration file in the logfile, so it is a good idea to look at the log at startup time to check for any problems. Most buildmaster activities will cause lines to be added to the log.

2.2.6.4. Shutdown

To stop a buildmaster or worker manually, use:

buildbot stop [ BASEDIR ]
# or
buildbot-worker stop [ WORKER_BASEDIR ]

This simply looks for the twistd.pid file and kills whatever process is identified within.

At system shutdown, all processes are sent a SIGKILL. The buildmaster and worker will respond to this by shutting down normally.

The buildmaster will respond to a SIGHUP by re-reading its config file. Of course, this only works on Unix-like systems with signal support and not on Windows. The following shortcut is available:

buildbot reconfig [ BASEDIR ]

When you update the Buildbot code to a new release, you will need to restart the buildmaster and/or worker before they can take advantage of the new code. You can do a buildbot stop BASEDIR and buildbot start BASEDIR in succession, or you can use the restart shortcut, which does both steps for you:

buildbot restart [ BASEDIR ]

Workers can similarly be restarted with:

buildbot-worker restart [ BASEDIR ]

There are certain configuration changes that are not handled cleanly by buildbot reconfig. If this occurs, buildbot restart is a more robust way to fully switch over to the new configuration.

buildbot restart may also be used to start a stopped Buildbot instance. This behavior is useful when writing scripts that stop, start, and restart Buildbot.

A worker may also be gracefully shutdown from the web UI. This is useful to shutdown a worker without interrupting any current builds. The buildmaster will wait until the worker has finished all its current builds, and will then tell the worker to shutdown.

2.3. Concepts

This chapter defines some of the basic concepts that Buildbot uses. You’ll need to understand how Buildbot sees the world to configure it properly.

2.3.1. Source identification

The following concepts are used within Buildbot to describe source code that is being built:

Repository: A repository is a location where files tracked by a version control system reside. Usually, it is identified by a URL or a location on a disk. It contains a subset of the history of a codebase.
Codebase: A codebase is a collection of related files and their history tracked as a unit by version control systems. The files and their history are stored in one or more repositories. For example, the primary repository for the Buildbot codebase is at https://github.com/buildbot/buildbot/. There are also more than a thousand forks of Buildbot. These repositories, while storing potentially very old versions of Buildbot code, still contain the same codebase.
Project: A project is a set of one or more codebases that together may be built and produce some end artifact. For example, an application may be comprised of two codebases - one for the code and one for the test data, the latter of which occupies a lot of space. Building and testing such an application requires acquiring code from both codebases.
Revision:: A revision is an textual identifier used by most version control systems to uniquely specify a particular version of the source code in a particular codebase.
Source stamp:: A source stamp is a collection of information needed to identify a particular version of code on a certain codebase. In most version control systems, source stamps only store a revision. On other version control systems, a branch is also required.
Source stamp set:: A source stamp set is a set of source stamps to identify a particular version of code on a certain project. Like a project is a collection of codebases, a source stamp set is a collection of source stamps, one for each codebase within a project.

In order to build a project, Buildbot only needs to know a source stamp set corresponding to that project. This source stamp set has a source stamp for each codebase comprising the project. In turn, each source stamp has enough information to identify a particular version of the code within the codebase.

2.3.2. Change sources

Change sources are user-configurable components that interact with external version control systems and retrieve new code. Internally, new code is represented as Changes which roughly correspond to a single commit or changeset. The changes are sent to the schedulers which then decide whether new builds should be created for these new code changes.

The design of Buildbot requires the workers to have their own copies of the source code, thus change sources is an optional component as long as there are no schedulers that create new builds based on new code commit events.

2.3.3. Changes

A Change is an abstract way Buildbot uses to represent a single change to the source files, performed by a developer. In version control systems that support the notion of atomic check-ins, a change represents a changeset or commit.

Changes are used for the Change sources to communicate with Schedulers.

A Change comprises the following information:

the developer who is responsible for the change

the list of files that the change added, removed or modified

the message of the commit

the repository, the codebase and the project that the change corresponds to

the revision and the branch of the commit

2.3.4. Schedulers

A scheduler is a component that decides when to start a build. The decision could be based on time, on new code being committed or on similar events.

Schedulers are responsible for creating Build Requests which identify a request to start a build on a specific version of the source code.

Each Buildmaster has a set of scheduler objects, each of which gets a copy of every incoming Change. The Schedulers are responsible for deciding when Builds should be run. Some Buildbot installations might have a single scheduler, while others may have several, each for a different purpose.

2.3.5. BuildRequests

A BuildRequest is a request to start a specific build. A BuildRequest consists of the following information:

the name of the Builder (see below) that will perform the build.

the set of SourceStamps (see above) that specify the version of the source tree to build and/or test.

Two build requests representing the same version of the source code and the same builder may be merged. The user may configure additional restrictions for determining mergeability of build requests.

2.3.6. Builders and Build Factories

A Builder is responsible for creating new builds from BuildRequests. Creating a new build is essentially determining the following properties of the subsequent build:

the exact steps a build will execute

the workers that the build may run on

The sequence of steps to run is performed by user-configurable BuildFactory that is attached to each Builder by the user.

A Builder will attempt to create a Build from a BuildRequest as soon as it is possible, that is, as soon as the associated worker becomes free. When a worker becomes free, the build master will select the oldest BuildRequest that can run on that worker and notify the corresponding Builder to maybe start a build out of it.

Each Builder by default runs completely independently. This means, that a worker that has N builders attached to it, may potentially attempt to run N builds concurrently. This level of concurrency may be controlled by various kinds of Interlocks.

At a low level, each builder has its own exclusive directory on the build master and one exclusive directory on each of the workers it is attached to. The directory on the master is used for keeping status information. The directories on the workers are used as a location where the actual checkout, compilation and testing steps happen.

For easier management in the Web UI related builders may be grouped into projects.

2.3.7. Builds

A Build represents a single compile or test run of a particular version of a source code. A build is comprised of a series of steps. The steps may be arbitrary. For example, for compiled software a build generally consists of the checkout, configure, make, and make check sequence. For interpreted projects like Python modules, a build is generally a checkout followed by an invocation of the bundled test suite.

Builds are created by instances of Builder (see above).

2.3.8. BuildSets

A BuildSet represents a set of potentially not yet created Builds that all compile and/or test the same version of the source tree. It tracks whether this set of builds as a whole succeeded or not. The information that is stored in a BuildSet is a set of SourceStamps which define the version of the code to test and a set of Builders which define what builds to create.

2.3.9. Workers

A Worker corresponds to an environment where builds are executed. A single physical machine must run at least one Worker in order for Buildbot to be able to utilize it for running builds. Multiple Workers may run on a single machine to provide different environments that can reuse the same hardware by means of containers or virtual machines.

Each builder is associated with one or more Workers. For example, a builder which is used to perform macOS builds (as opposed to Linux or Windows builds) should naturally be associated with a Mac worker.

If multiple workers are available for any given builder, you will have some measure of redundancy: in case one worker goes offline, the others can still keep the Builder working. In addition, multiple workers will allow multiple simultaneous builds for the same Builder, which might be useful if you have a lot of forced or try builds taking place.

Ideally, each Worker that is configured for a builder should be identical. Otherwise build or test failures will be dependent on which worker the build is run and this will complicate investigations of failures.

2.3.10. Users

Buildbot has a somewhat limited awareness of users. It assumes the world consists of a set of developers, each of whom can be described by a couple of simple attributes. These developers make changes to the source code, causing builds which may succeed or fail.

Users also may have different levels of authorization when issuing Buildbot commands, such as forcing a build from the web interface or from an IRC channel.

Each developer is primarily known through the source control system. Each Change object that arrives is tagged with a who field that typically gives the account name (on the repository machine) of the user responsible for that change. This string is displayed on the HTML status pages and in each Build's blamelist.

To do more with the User than just refer to them, this username needs to be mapped into an address of some sort. The responsibility for this mapping is left up to the status module which needs the address. In the future, the responsibility for managing users will be transferred to User Objects.

The who fields in git Changes are used to create User Objects, which allows for more control and flexibility in how Buildbot manages users.

2.3.10.1. User Objects

User Objects allow Buildbot to better manage users throughout its various interactions with users (see Change Sources and Changes and Reporters). The User Objects are stored in the Buildbot database and correlate the various attributes that a user might have: irc, Git, etc.

Changes

Incoming Changes all have a who attribute attached to them that specifies which developer is responsible for that Change. When a Change is first rendered, the who attribute is parsed and added to the database, if it doesn’t exist, or checked against an existing user. The who attribute is formatted in different ways depending on the version control system that the Change came from.

git: who attributes take the form Full Name <Email>.
svn: who attributes are of the form Username.
hg: who attributes are free-form strings, but usually adhere to similar conventions as git attributes (Full Name <Email>).
cvs: who attributes are of the form Username.
darcs: who attributes contain an Email and may also include a Full Name like git attributes.
bzr: who attributes are free-form strings like hg, and can include a Username, Email, and/or Full Name.

Tools

For managing users manually, use the buildbot user command, which allows you to add, remove, update, and show various attributes of users in the Buildbot database (see Command-line Tool).

Uses

Correlating the various bits and pieces that Buildbot views as users also means that one attribute of a user can be translated into another. This provides a more complete view of users throughout Buildbot.

One such use is being able to find email addresses based on a set of Builds to notify users through the MailNotifier. This process is explained more clearly in Email Addresses.

Another way to utilize User Objects is through UsersAuth for web authentication. To use UsersAuth, you need to set a bb_username and bb_password via the buildbot user command line tool to check against. The password will be encrypted before it gets stored in the database along with other user attributes.

2.3.10.2. Doing Things With Users

Each change has a single user who is responsible for it. Most builds have a set of changes: the build generally represents the first time these changes have been built and tested by the Buildbot. The build has a blamelist that is the union of the users responsible for all of the build’s changes. If the build was created by a Try Schedulers this list will include the submitter of the try job if known.

The build provides a list of users who are interested in the build – the interested users. Usually this is equal to the blamelist, but may also be expanded, e.g., to include the current build sherrif or a module’s maintainer.

If desired, buildbot can notify the interested users until the problem is resolved.

2.3.10.3. Email Addresses

The MailNotifier is a status target which can send emails about the results of each build. It accepts a static list of email addresses to which each message should be delivered, but it can also be configured to send emails to a Build's Interested Users. To do this, it needs a way to convert User names into email addresses.

For many VCSs, the User name is actually an account name on the system which hosts the repository. As such, turning the name into an email address is simply a matter of appending @repositoryhost.com. Some projects use other kinds of mappings (for example the preferred email address may be at project.org, despite the repository host being named cvs.project.org), and some VCSs have full separation between the concept of a user and that of an account on the repository host (like Perforce). Some systems (like Git) put a full contact email address in every change.

To convert these names to addresses, the MailNotifier uses an EmailLookup object. This provides a getAddress method which accepts a name and (eventually) returns an address. The default MailNotifier module provides an EmailLookup which simply appends a static string, configurable when the notifier is created. To create more complex behaviors (perhaps using an LDAP lookup, or using finger on a central host to determine a preferred address for the developer), provide a different object as the lookup argument.

If an EmailLookup object isn’t given to the MailNotifier, the MailNotifier will try to find emails through User Objects. If every user in the Build’s Interested Users list has an email in the database for them, this will work the same as if an EmailLookup object was used. If a user whose change led to a Build doesn’t have an email attribute, that user will not receive an email. If extraRecipients is given, those users still get an email when the EmailLookup object is not specified.

In the future, when the Problem mechanism has been set up, Buildbot will need to send emails to arbitrary Users. It will do this by locating a MailNotifier-like object among all the buildmaster’s status targets, and asking it to send messages to various Users. This means the User-to-address mapping only has to be set up once, in your MailNotifier, and every email message buildbot emits will take advantage of it.

2.3.10.4. IRC Nicknames

Like MailNotifier, the buildbot.reporters.irc.IRC class provides a status target which can announce the results of each build. It also provides an interactive interface by responding to online queries posted in the channel or sent as private messages.

In the future, buildbot can be configured to map User names to IRC nicknames, to watch for the recent presence of these nicknames, and to deliver build status messages to the interested parties. Like MailNotifier does for email addresses, the IRC object will have an IRCLookup which is responsible for nicknames. The mapping can be set up statically, or it can be updated by online users themselves (by claiming a username with some kind of buildbot: i am user warner commands).

Once the mapping is established, buildbot can then ask the IRC object to send messages to various users. It can report on the likelihood that the user saw the given message (based upon how long the user has been inactive on the channel), which might prompt the Problem Hassler logic to send them an email message instead.

These operations and authentication of commands issued by particular nicknames will be implemented in User Objects.

2.3.11. Build Properties

Each build has a set of Build Properties, which can be used by its build steps to modify their actions.

The properties are represented as a set of key-value pairs. Effectively, a single property is a variable that, once set, can be used by subsequent steps in a build to modify their behaviour. The value of a property can be a number, a string, a list or a dictionary. Lists and dictionaries can contain other lists or dictionaries. Thus, the value of a property could be any arbitrarily complex structure.

Properties work pretty much like variables, so they can be used to implement all manner of functionality.

The following are a couple of examples:

By default, the name of the worker that runs the build is set to the workername property. If there are multiple different workers and the actions of the build depend on the exact worker, some users may decide that it’s more convenient to vary the actions depending on the workername property instead of creating separate builders for each worker.

In most cases, the build does not know the exact code revision that will be tested until it checks out the code. This information is only known after a source step runs. To give this information to the subsequent steps, the source step records the checked out revision into the got_revision property.

2.4. Secret Management

2.4.1. Requirements

Buildbot steps might need secrets to execute their actions. Secrets are used to execute commands or to create authenticated network connections. Secrets may be a SSH key, a password, or a file content like a wgetrc file or a public SSH key. To preserve confidentiality, the secret values must not be printed or logged in the twisted or step logs. Secrets must not be stored in the Buildbot configuration (master.cfg), as the source code is usually shared in SCM like git.

2.4.2. How to use Buildbot Secret Management

2.4.2.1. Secrets and providers

Buildbot implements several providers for secrets retrieval:

File system based: secrets are written in a file. This is a simple solution for example when secrets are managed by a config management system like Ansible Vault.
Third party backend based: secrets are stored by a specialized software. These solutions are usually more secure.

Secrets providers are configured if needed in the master configuration. Multiple providers can be configured at once. The secret manager is a Buildbot service. The secret manager returns the specific provider results related to the providers registered in the configuration.

2.4.2.2. How to use secrets in Buildbot

Secret can be used in Buildbot via the IRenderable mechanism. Two IRenderable actually implement secrets. Interpolate can be used if you need to mix secrets and other interpolation in the same argument. Secret can be used if your secret is directly used as a component argument.

Secret

Secret is a simple renderable which directly renders a secret.
Secret("secretName")

As argument to steps

The following example shows a basic usage of secrets in Buildbot.

from buildbot.plugins import secrets, util
# First we declare that the secrets are stored in a directory of the filesystem
# each file contains one secret identified by the filename
c['secretsProviders'] = [secrets.SecretInAFile(dirname="/path/toSecretsFiles")]

# then in a buildfactory:

# use a secret on a shell command via Interpolate
f1.addStep(ShellCommand(
    util.Interpolate("wget -u user -p '%(secret:userpassword)s' '%(prop:urltofetch)s'")))
# .. or non shell form:
f1.addStep(ShellCommand(["wget", "-u", "user", "-p",
                         util.Secret("userpassword"),
                         util.Interpolate("%(prop:urltofetch)s")]))

Secrets are also interpolated in the build like properties are. Their values will be used in a command line for example.

As argument to services

You can use secrets to configure services. All services arguments are not compatible with secrets. See their individual documentation for details.

# First we declare that the secrets are stored in a directory of the filesystem
# each file contains one secret identified by the filename
c['secretsProviders'] = [secrets.SecretInAFile(dirname="/path/toSecretsFiles")]

# then for a reporter:
c['services'] = [GitHubStatusPush(token=util.Secret("githubToken"))]

2.4.2.3. Secrets storages

SecretInAFile

c['secretsProviders'] = [secrets.SecretInAFile(dirname="/path/toSecretsFiles")]

In the passed directory, every file contains a secret identified by the filename.

e.g: a file user contains the text pa$$w0rd.

Arguments:

dirname: (required) Absolute path to directory containing the files with a secret.
strip: (optional) if True (the default), trailing newlines are removed from the file contents.

HashiCorpVaultKvSecretProvider

c['secretsProviders'] = [
    secrets.HashiCorpVaultKvSecretProvider(
        authenticator=secrets.VaultAuthenticatorApprole(roleId="<role-guid>",
                                                        secretId="<secret-guid>"),
        vault_server="http://localhost:8200",
        secrets_mount="kv")
]

HashiCorpVaultKvSecretProvider allows to use HashiCorp Vault KV secret engine as secret provider. Other secret engines are not supported by this particular provider. For more information about Vault please visit: Vault: https://www.vaultproject.io/

In order to use this secret provider, optional dependency hvac needs to be installed (pip install hvac).

It supports different authentication methods with ability to re-authenticate when authentication token expires (not possible using HvacAuthenticatorToken).

Parameters accepted by HashiCorpVaultKvSecretProvider:

authenticator: required parameter, specifies Vault authentication method. Possible authenticators are:

VaultAuthenticatorToken(token): simplest authentication by directly providing the authentication token. This method cannot benefit from re-authentication mechanism and when token expires, secret provider will just stop working.

VaultAuthenticatorApprole(roleId, secretId): approle authentication using roleId and secretId. This is common method for automation tools fetching secrets from vault.

vault_server: required parameter, specifies URL of vault server.

secrets_mount: specifies mount point of KV secret engine in vault, default value is “secret”.

api_version: version of vault KV secret engine. Supported versions are 1 and 2, default value is 2.

path_delimiter: character used to separate path and key name in secret identifiers. Default value is “|”.

path_escape: escape character used in secret identifiers to allow escaping of path_delimiter character in path or key values. Default value is “".

The secret identifiers that need to be passed to, e.g. Interpolate, have format: "path/to/secret:key". In case path or key name does contain colon character, it is possible to escape it using “" or specify different separator character using path_delimiter parameter when initializing secret provider.

Example use:

passwd = util.Secret('path/to/secret:password')

SecretInPass

c['secretsProviders'] = [secrets.SecretInPass(
                        gpgPassphrase="passphrase",
                        dirname="/path/to/password/store"
)]

Passwords can be stored in a unix password store, encrypted using GPG keys. Buildbot can query secrets via the pass binary found in the PATH of each worker. While pass allows for multiline entries, the secret must be on the first line of each entry. The only caveat is that all passwords Buildbot needs to access have to be encrypted using the same GPG key.

For more information about pass, please visit pass: https://www.passwordstore.org/

Arguments:

gpgPassphrase: (optional) Pass phrase to the GPG decryption key, if any
dirname: (optional) Absolute path to the password store directory, defaults to ~/.password-store

2.4.2.4. How to populate secrets in a build

To populate secrets in files during a build, 2 steps are used to create and delete the files on the worker. The files will be automatically deleted at the end of the build.

       f = BuildFactory()
       with f.withSecrets(secrets_list):
           f.addStep(step_definition)

or

f = BuildFactory()
f.addSteps([list_of_step_definitions], withSecrets=secrets_list)

In both cases the secrets_list is a list of (secret path, secret value) tuples.

secrets_list = [('/first/path', Interpolate('write something and %(secret:somethingmore)s')),
                ('/second/path', Interpolate('%(secret:othersecret)s'))]

The Interpolate class is used to render the value during the build execution.

2.4.2.5. How to configure a Vault instance

Vault being a very generic system, it can be complex to install for the first time. Here is a simple tutorial to install the minimal Vault to use with Buildbot.

Use Docker to install Vault

A Docker image is available to help users installing Vault. Without any arguments, the command launches a Docker Vault developer instance, easy to use and test the functions. The developer version is already initialized and unsealed. To launch a Vault server please refer to the VaultDocker documentation:

In a shell:

docker run vault

Starting the vault instance

Once the Docker image is created, launch a shell terminal on the Docker image:

docker exec -i -t ``docker_vault_image_name`` /bin/sh

Then, export the environment variable VAULT_ADDR needed to init Vault.

export VAULT_ADDR='vault.server.adress'

Writing secrets

By default the official docker instance of Vault is initialized with a mount path of ‘secret’, a KV v1 secret engine, and a second KV engine (v2) at ‘secret/data’. Currently, Buildbot is “hard wired” to expect KV v2 engines to reside within this “data” sub path. Provision is made to set a top level path via the “secretsmount” argument: defaults to “secret”. To add a new secret:

vault kv put secret/new_secret_key value=new_secret_value

2.5. Configuration

The following sections describe the configuration of the various Buildbot components. The information available here is sufficient to create basic build and test configurations, and does not assume great familiarity with Python.

In more advanced Buildbot configurations, Buildbot acts as a framework for a continuous-integration application. The next section, Customization, describes this approach, with frequent references into the development documentation.

2.5.1. Configuring Buildbot

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 workers 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.

2.5.1.1. Config File Format

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 the basic configuration, though; you can just copy the sample file’s syntax. If you are comfortable writing Python code, however, you can use all the power of a full programming language to build 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 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'].

See Buildmaster Configuration Index for a full list of BuildMasterConfig keys.

Basic Python Syntax

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 instantiations) can use named parameters, like steps.ShellCommand(command=["trial", "hello"]).

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, and then it is populated with a variety of keys, described section-by-section in the subsequent chapters.

2.5.1.2. Predefined Config File Symbols

The following symbols are automatically available for use in the configuration file.

basedir

the base directory for the buildmaster. This string has not been expanded, so it may start with a tilde. It needs to be expanded before use. The config file is located in:

os.path.expanduser(os.path.join(basedir, 'master.cfg'))

__file__

the absolute path of the config file. The config file’s directory is located in os.path.dirname(__file__).

2.5.1.3. Testing the Config File

To verify that the config file is well-formed and contains no deprecated or invalid elements, use the checkconfig command, passing it either a master directory or a config file.

% buildbot checkconfig master.cfg
Config file is good!
# or
% buildbot checkconfig /tmp/masterdir
Config file is good!

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:

% buildbot checkconfig master.cfg
Configuration Errors:
c['workers'] must be a list of Worker instances
no workers are configured
builder 'smoketest' uses unknown workers 'linux-002'

If the config file is simply broken, that will be caught too:

% buildbot checkconfig master.cfg
error while parsing config file:
Traceback (most recent call last):
File "/home/buildbot/master/bin/buildbot", line 4, in <module>
    runner.run()
File "/home/buildbot/master/buildbot/scripts/runner.py", line 1358, in run
    if not doCheckConfig(so):
File "/home/buildbot/master/buildbot/scripts/runner.py", line 1079, in doCheckConfig
    return cl.load(quiet=quiet)
File "/home/buildbot/master/buildbot/scripts/checkconfig.py", line 29, in load
    self.basedir, self.configFileName)
--- <exception caught here> ---
File "/home/buildbot/master/buildbot/config.py", line 147, in loadConfig
    exec f in localDict
exceptions.SyntaxError: invalid syntax (master.cfg, line 52)
Configuration Errors:
error while parsing config file: invalid syntax (master.cfg, line 52) (traceback in logfile)

2.5.1.4. Loading the Config File

The config file is only read at specific points in time. It is first read when the buildmaster is launched.

Note

If the configuration is invalid, the master will display the errors in the console output, but will not exit.

Reloading the Config File (reconfig)

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 the output.

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 command is changed), this change will apply only for new Builds. Any existing build that is currently running or was already queued will be allowed to finish using the old configuration.

Note that if any lock is renamed, old and new instances of the lock will be completely unrelated in the eyes of the buildmaster. This means that buildmaster will be able to start new builds that would otherwise have waited for the old lock to be released.

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 https://docs.python.org/3/library/importlib.html and importlib.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.

The bbproto project (at https://github.com/dabrahams/bbproto) may help to construct large (multi-file) configurations which can be effectively reloaded and reconfigured.

2.5.2. Global Configuration

The keys in this section affect the operations of the buildmaster globally.

2.5.2.1. Database Specification 

Buildbot requires a connection to a database to maintain certain state information, such as tracking pending build requests. In the default configuration Buildbot uses a file-based SQLite database, stored in the state.sqlite file of the master’s base directory.

Important

SQLite3 is perfectly suitable for small setups with a few users. However, it does not scale well with large numbers of builders, workers and users. If you expect your Buildbot to grow over time, it is strongly advised to use a real database server (e.g., MySQL or Postgres).

A SQLite3 database may be migrated to a real database server using buildbot copy-db script.

See the Using A Database Server section for more details.

Override this configuration with the db_url parameter.

Buildbot accepts a database configuration in a dictionary named db. All keys are optional:

c['db'] = {
    'db_url' : 'sqlite:///state.sqlite',
}

The db_url key indicates the database engine to use. The format of this parameter is completely documented at http://www.sqlalchemy.org/docs/dialects/, but is generally of the form:

"driver://[username:password@]host:port/database[?args]"

This parameter can be specified directly in the configuration dictionary, as c['db_url'], although this method is deprecated.

The following sections give additional information for particular database backends:

SQLite

For sqlite databases, since there is no host and port, relative paths are specified with sqlite:/// and absolute paths with sqlite:////. For example:

c['db_url'] = "sqlite:///state.sqlite"

SQLite requires no special configuration.

MySQL

c['db_url'] = "mysql://username:password@example.com/database_name?max_idle=300"

The max_idle argument for MySQL connections is unique to Buildbot and should be set to something less than the wait_timeout configured for your server. This controls the SQLAlchemy pool_recycle parameter, which defaults to no timeout. Setting this parameter ensures that connections are closed and re-opened after the configured amount of idle time. If you see errors such as _mysql_exceptions.OperationalError: (2006, 'MySQL server has gone away'), this means your max_idle setting is probably too high. show global variables like 'wait_timeout'; will show what the currently configured wait_timeout is on your MySQL server.

Buildbot requires use_unique=True and charset=utf8, and will add them automatically, so they do not need to be specified in db_url.

MySQL defaults to the MyISAM storage engine, but this can be overridden with the storage_engine URL argument.

Postgres

c['db_url'] = "postgresql://username:password@hostname/dbname"

PosgreSQL requires no special configuration.

2.5.2.2. MQ Specification 

Buildbot uses a message-queueing system to handle communication within the master. Messages are used to indicate events within the master, and components that are interested in those events arrange to receive them.

The message queueing implementation is configured as a dictionary in the mq option. The type key describes the type of MQ implementation to be used. Note that the implementation type cannot be changed in a reconfig.

The available implementation types are described in the following sections.

Simple

c['mq'] = {
    'type' : 'simple',
    'debug' : False,
}

This is the default MQ implementation. Similar to SQLite, it has no additional software dependencies, but does not support multi-master mode.

Note that this implementation also does not support message persistence across a restart of the master. For example, if a change is received, but the master shuts down before the schedulers can create build requests for it, then those schedulers will not be notified of the change when the master starts again.

The debug key, which defaults to False, can be used to enable logging of every message produced on this master.

Wamp

Note

At the moment, wamp is the only message queue implementation for multimaster. It has been privileged as this is the only message queue that has very solid support for Twisted. Other more common message queue systems like RabbitMQ (using the AMQP protocol) do not have a convincing driver for twisted, and this would require to run on threads, which will add an important performance overhead.

c['mq'] = {
    'type' : 'wamp',
    'router_url': 'ws://localhost:8080/ws',
    'realm': 'realm1',
    # valid are: none, critical, error, warn, info, debug, trace
    'wamp_debug_level' : 'error'
}

This is a MQ implementation using the wamp protocol. This implementation uses Python Autobahn wamp client library, and is fully asynchronous (no use of threads). To use this implementation, you need a wamp router like Crossbar.

The implementation does not yet support wamp authentication. This MQ allows buildbot to run in multi-master mode.

router_url (mandatory): points to your router websocket url.: Buildbot is only supporting wamp over websocket, which is a sub-protocol of http. SSL is supported using wss:// instead of ws://.

realm (optional, defaults to buildbot): defines the wamp realm to use for your buildbot messages.

wamp_debug_level (optional, defaults to error): defines the log level of autobahn.

You must use a router with very reliable connection to the master. If for some reason, the wamp connection is lost, then the master will stop, and should be restarted via a process manager.

Crossbar

The default Crossbar setup will just work with Buildbot, provided you use the example mq configuration below, and start Crossbar with:

# of course, you should work in a virtualenv...
pip install crossbar
crossbar init
crossbar start

.crossbar/config.json:

{
    "version": 2,
    "controller": {},
    "workers": [
        {
            "type": "router",
            "realms": [
                {
                    "name": "test_realm",
                    "roles": [
                        {
                            "name": "anonymous",
                            "permissions": [
                                {
                                    "uri": "",
                                    "match": "prefix",
                                    "allow": {
                                        "call": true,
                                        "register": true,
                                        "publish": true,
                                        "subscribe": true
                                    },
                                    "disclose": {
                                        "caller": false,
                                        "publisher": false
                                    },
                                    "cache": true
                                }
                            ]
                        }
                    ]
                }
            ],
            "transports": [
                {
                    "type": "web",
                    "endpoint": {
                        "type": "tcp",
                        "port": 1245
                    },
                    "paths": {
                        "ws": {
                            "type": "websocket"
                        }
                    }
                }
            ]
        }
    ]
}

Buildbot can be configured to use Crossbar by the following:

c["mq"] = {
    "type" : "wamp",
    "router_url": "ws://localhost:1245/ws",
    "realm": "test_realm",
    "wamp_debug_level" : "warn"
}

Please refer to Crossbar documentation for more details.

2.5.2.3. Multi-master mode 

See Multimaster for details on the multi-master mode in Buildbot Nine.

By default, Buildbot makes coherency checks that prevent typos in your master.cfg. It makes sure schedulers are not referencing unknown builders, and enforces there is at least one builder.

In the case of an asymmetric multimaster, those coherency checks can be harmful and prevent you to implement what you want. For example, you might want to have one master dedicated to the UI, so that a big load generated by builds will not impact page load times.

To enable multi-master mode in this configuration, you will need to set the multiMaster option so that buildbot doesn’t warn about missing schedulers or builders.

# Enable multiMaster mode; disables warnings about unknown builders and
# schedulers
c['multiMaster'] = True
c['db'] = {
    'db_url' : 'mysql://...',
}
c['mq'] = {  # Need to enable multimaster aware mq. Wamp is the only option for now.
    'type' : 'wamp',
    'router_url': 'ws://localhost:8080',
    'realm': 'realm1',
    # valid are: none, critical, error, warn, info, debug, trace
    'wamp_debug_level' : 'error'
}

2.5.2.4. Site Definitions 

Three basic settings describe the buildmaster in status reports:

c['title'] = "Buildbot"
c['titleURL'] = "http://buildbot.sourceforge.net/"

title is a short string that will appear at the top of this buildbot installation’s home page (linked to the titleURL).

titleURL is a URL string that must end with a slash (/). HTML status displays will show title as a link to titleURL. This URL is often used to provide a link from buildbot HTML pages to your project’s home page.

The buildbotURL string should point to the location where the buildbot’s internal web server is visible. This URL must end with a slash (/).

When status notices are sent to users (e.g., by email or over IRC), buildbotURL will be used to create a URL to the specific build or problem that they are being notified about.

2.5.2.5. Log Handling 

c['logCompressionMethod'] = 'gz'
c['logMaxSize'] = 1024*1024 # 1M
c['logMaxTailSize'] = 32768
c['logEncoding'] = 'utf-8'

The logCompressionLimit enables compression of build logs on disk for logs that are bigger than the given size, or disables that completely if set to False. The default value is 4096, which should be a reasonable default on most file systems. This setting has no impact on status plugins, and merely affects the required disk space on the master for build logs.

The logCompressionMethod controls what type of compression is used for build logs. The default is ‘gz’, and the other valid option are ‘raw’ (no compression), ‘gz’ or ‘lz4’ (required lz4 package).

Please find below some stats extracted from 50x “trial Pyflakes” runs (results may differ according to log type).

Space saving details
compression	raw log size	compressed log size	space saving	compression speed
bz2	2.981 MB	0.603 MB	79.77%	3.433 MB/s
gz	2.981 MB	0.568 MB	80.95%	6.604 MB/s
lz4	2.981 MB	0.844 MB	71.68%	77.668 MB/s

The logMaxSize parameter sets an upper limit (in bytes) to how large logs from an individual build step can be. The default value is None, meaning no upper limit to the log size. Any output exceeding logMaxSize will be truncated, and a message to this effect will be added to the log’s HEADER channel.

If logMaxSize is set, and the output from a step exceeds the maximum, the logMaxTailSize parameter controls how much of the end of the build log will be kept. The effect of setting this parameter is that the log will contain the first logMaxSize bytes and the last logMaxTailSize bytes of output. Don’t set this value too high, as the tail of the log is kept in memory.

The logEncoding parameter specifies the character encoding to use to decode bytestrings provided as logs. It defaults to utf-8, which should work in most cases, but can be overridden if necessary. In extreme cases, a callable can be specified for this parameter. It will be called with byte strings, and should return the corresponding Unicode string.

This setting can be overridden for a single build step with the logEncoding step parameter. It can also be overridden for a single log file by passing the logEncoding parameter to addLog.

2.5.2.6. Data Lifetime 

Horizons

Previously Buildbot implemented a global configuration for horizons. Now it is implemented as a utility Builder, and shall be configured via the JanitorConfigurator.

Caches

c['caches'] = {
    'Changes' : 100,     # formerly c['changeCacheSize']
    'Builds' : 500,      # formerly c['buildCacheSize']
    'chdicts' : 100,
    'BuildRequests' : 10,
    'SourceStamps' : 20,
    'ssdicts' : 20,
    'objectids' : 10,
    'usdicts' : 100,
}

The caches configuration key contains the configuration for Buildbot’s in-memory caches. These caches keep frequently-used objects in memory to avoid unnecessary trips to the database. Caches are divided by object type, and each has a configurable maximum size.

The default size for each cache is 1, except where noted below. A value of 1 allows Buildbot to make a number of optimizations without consuming much memory. Larger, busier installations will likely want to increase these values.

The available caches are:

Changes

the number of change objects to cache in memory. This should be larger than the number of changes that typically arrive in the span of a few minutes, otherwise your schedulers will be reloading changes from the database every time they run. For distributed version control systems, like Git or Hg, several thousand changes may arrive at once, so setting this parameter to something like 10000 isn’t unreasonable.

This parameter is the same as the deprecated global parameter changeCacheSize. Its default value is 10.

Builds

The buildCacheSize parameter gives the number of builds for each builder which are cached in memory. This number should be larger than the number of builds required for commonly-used status displays (the waterfall or grid views), so that those displays do not miss the cache on a refresh.

This parameter is the same as the deprecated global parameter buildCacheSize. Its default value is 15.

chdicts

The number of rows from the changes table to cache in memory. This value should be similar to the value for Changes.

BuildRequests

The number of BuildRequest objects kept in memory. This number should be higher than the typical number of outstanding build requests. If the master ordinarily finds jobs for BuildRequests immediately, you may set a lower value.

SourceStamps

the number of SourceStamp objects kept in memory. This number should generally be similar to the number BuildRequesets.

ssdicts

The number of rows from the sourcestamps table to cache in memory. This value should be similar to the value for SourceStamps.

objectids

The number of object IDs - a means to correlate an object in the Buildbot configuration with an identity in the database–to cache. In this version, object IDs are not looked up often during runtime, so a relatively low value such as 10 is fine.

usdicts

The number of rows from the users table to cache in memory. Note that for a given user there will be a row for each attribute that user has.

c[‘buildCacheSize’] = 15

2.5.2.7. Merging Build Requests 

c['collapseRequests'] = True

This is a global default value for builders’ collapseRequests parameter, and controls the merging of build requests.

This parameter can be overridden on a per-builder basis. See Collapsing Build Requests for the allowed values for this parameter.

2.5.2.8. Prioritizing Builders 

def prioritizeBuilders(buildmaster, builders):
    ...
c['prioritizeBuilders'] = prioritizeBuilders

By default, buildbot will attempt to start builds on builders in order, beginning with the builder with the oldest pending request. Customize this behavior with the prioritizeBuilders configuration key, which takes a callable. See Builder Priority Functions for details on this callable.

This parameter controls the order that the buildmaster can start builds, and is useful in situations where there is resource contention between builders, e.g., for a test database. It does not affect the order in which a builder processes the build requests in its queue. For that purpose, see Prioritizing Builds.

2.5.2.9. Prioritizing Workers 

By default Buildbot will select worker for a build randomly from available workers. This can be adjusted by select_next_worker function in global master configuration and additionally by nextWorker per-builder configuration parameter. These two functions work exactly the same:

The function is passed three arguments, the Builder object which is assigning a new job, a list of WorkerForBuilder objects and the BuildRequest.

The function should return one of the WorkerForBuilder objects, or None if none of the available workers should be used. The function can optionally return a Deferred, which should fire with the same results.

def select_next_worker(builder, workers, buildrequest):
    ...
c["select_next_worker"] = select_next_worker

2.5.2.10. Setting the PB Port for Workers 

c['protocols'] = {"pb": {"port": 10000}}

The buildmaster will listen on a TCP port of your choosing for connections from workers. It can also use this port for connections from remote Change Sources, status clients, and debug tools. This port should be visible to the outside world, and you’ll need to tell your worker admins about your choice.

It does not matter which port you pick, as long it is externally visible; however, you should probably use something larger than 1024, since most operating systems don’t allow non-root processes to bind to low-numbered ports. If your buildmaster is behind a firewall or a NAT box of some sort, you may have to configure your firewall to permit inbound connections to this port.

c['protocols']['pb']['port'] can also be used as a connection string, as defined in the ConnectionStrings guide.

This means that you can have the buildmaster listen on a localhost-only port by doing:

c['protocols'] = {"pb": {"port": "tcp:10000:interface=127.0.0.1"}}

This might be useful if you only run workers on the same machine, and they are all configured to contact the buildmaster at localhost:10000.

connection strings can also be used to configure workers connecting over TLS. The syntax is then

c['protocols'] = {"pb": {"port":
                         "ssl:9989:privateKey=master.key:certKey=master.crt"}}

Please note that IPv6 addresses with : must be escaped with as well as : in paths and in paths. Read more about the connection strings format in ConnectionStrings documentation.

2.5.2.11. Defining Global Properties 

The properties configuration key defines a dictionary of properties that will be available to all builds started by the buildmaster:

c['properties'] = {
    'Widget-version' : '1.2',
    'release-stage' : 'alpha'
}

2.5.2.12. Manhole 

Manhole is an interactive Python shell which allows full access to the Buildbot master instance. It is probably only useful for buildbot developers.

See documentation on Manhole implementations for available authentication and connection methods.

The manhole configuration key accepts a single instance of a Manhole class. For example:

from buildbot import manhole
c['manhole'] = manhole.PasswordManhole("tcp:1234:interface=127.0.0.1",
                                       "admin", "passwd",
                                       ssh_hostkey_dir="data/ssh_host_keys")

2.5.2.13. Metrics Options 

c['metrics'] = {
    "log_interval": 10,
    "periodic_interval": 10
}

metrics can be a dictionary that configures various aspects of the metrics subsystem. If metrics is None, then metrics collection, logging and reporting will be disabled.

log_interval determines how often metrics should be logged to twistd.log. It defaults to 60s. If set to 0 or None, then logging of metrics will be disabled. This value can be changed via a reconfig.

periodic_interval determines how often various non-event based metrics are collected, such as memory usage, uncollectable garbage, reactor delay. This defaults to 10s. If set to 0 or None, then periodic collection of this data is disabled. This value can also be changed via a reconfig.

Read more about metrics in the Metrics section in the developer documentation.

2.5.2.14. Statistics Service 

The Statistics Service (stats service for short) supports the collection of arbitrary data from within a running Buildbot instance and the export to a number of storage backends. Currently, only InfluxDB is supported as a storage backend. Also, InfluxDB (or any other storage backend) is not a mandatory dependency. Buildbot can run without it, although StatsService will be of no use in such a case. At present, StatsService can keep track of build properties, build times (start, end, duration) and arbitrary data produced inside Buildbot (more on this later).

Example usage:

captures = [stats.CaptureProperty('Builder1', 'tree-size-KiB'),
            stats.CaptureBuildDuration('Builder2')]
c['services'] = []
c['services'].append(stats.StatsService(
    storage_backends=[
        stats.InfluxStorageService('localhost', 8086, 'root', 'root', 'test', captures)
    ], name="StatsService"))

The services configuration value should be initialized as a list and a StatsService instance should be appended to it as shown in the example above.

Statistics Service

class buildbot.statistics.stats_service.StatsService

This is the main class for statistics services. It is initialized in the master configuration as shown in the example above. It takes two arguments:

storage_backends: A list of storage backends (see Storage Backends). In the example above, stats.InfluxStorageService is an instance of a storage backend. Each storage backend is an instance of subclasses of statsStorageBase.
name: The name of this service.

yieldMetricsValue: This method can be used to send arbitrary data for storage. (See Using StatsService.yieldMetricsValue for more information.)

Capture Classes

class buildbot.statistics.capture.CaptureProperty

Instance of this class declares which properties must be captured and sent to the Storage Backends. It takes the following arguments:

builder_name: The name of builder in which the property is recorded.
property_name: The name of property needed to be recorded as a statistic.
callback=None: (Optional) A custom callback function for this class. This callback function should take in two arguments - build_properties (dict) and property_name (str) and return a string that will be sent for storage in the storage backends.
regex=False: If this is set to True, then the property name can be a regular expression. All properties matching this regular expression will be sent for storage.

class buildbot.statistics.capture.CapturePropertyAllBuilders

Instance of this class declares which properties must be captured on all builders and sent to the Storage Backends. It takes the following arguments:

property_name: The name of property needed to be recorded as a statistic.
callback=None: (Optional) A custom callback function for this class. This callback function should take in two arguments - build_properties (dict) and property_name (str) and return a string that will be sent for storage in the storage backends.
regex=False: If this is set to True, then the property name can be a regular expression. All properties matching this regular expression will be sent for storage.

class buildbot.statistics.capture.CaptureBuildStartTime

Instance of this class declares which builders’ start times are to be captured and sent to Storage Backends. It takes the following arguments:

builder_name: The name of builder whose times are to be recorded.
callback=None: (Optional) A custom callback function for this class. This callback function should take in a Python datetime object and return a string that will be sent for storage in the storage backends.

class buildbot.statistics.capture.CaptureBuildStartTimeAllBuilders

Instance of this class declares start times of all builders to be captured and sent to Storage Backends. It takes the following arguments:

callback=None: (Optional) A custom callback function for this class. This callback function should take in a Python datetime object and return a string that will be sent for storage in the storage backends.

class buildbot.statistics.capture.CaptureBuildEndTime: Exactly like CaptureBuildStartTime except it declares the builders whose end time is to be recorded. The arguments are same as CaptureBuildStartTime.

class buildbot.statistics.capture.CaptureBuildEndTimeAllBuilders: Exactly like CaptureBuildStartTimeAllBuilders except it declares all builders’ end time to be recorded. The arguments are same as CaptureBuildStartTimeAllBuilders.

class buildbot.statistics.capture.CaptureBuildDuration

Instance of this class declares the builders whose build durations are to be recorded. It takes the following arguments:

builder_name: The name of builder whose times are to be recorded.
report_in='seconds': Can be one of three: 'seconds', 'minutes', or 'hours'. This is the units in which the build time will be reported.
callback=None: (Optional) A custom callback function for this class. This callback function should take in two Python datetime objects - a start_time and an end_time and return a string that will be sent for storage in the storage backends.

class buildbot.statistics.capture.CaptureBuildDurationAllBuilders

Instance of this class declares build durations to be recorded for all builders. It takes the following arguments:

report_in='seconds': Can be one of three: 'seconds', 'minutes', or 'hours'. This is the units in which the build time will be reported.
callback=None: (Optional) A custom callback function for this class. This callback function should take in two Python datetime objects - a start_time and an end_time and return a string that will be sent for storage in the storage backends.

class buildbot.statistics.capture.CaptureData

Instance of this capture class is for capturing arbitrary data that is not stored as build-data. Needs to be used in combination with yieldMetricsValue (see Using StatsService.yieldMetricsValue). Takes the following arguments:

data_name: The name of data to be captured. Same as in yieldMetricsValue.
builder_name: The name of builder whose times are to be recorded.
callback=None: The callback function for this class. This callback receives the data sent to yieldMetricsValue as post_data (see Using StatsService.yieldMetricsValue). It must return a string that is to be sent to the storage backends for storage.

class buildbot.statistics.capture.CaptureDataAllBuilders

Instance of this capture class for capturing arbitrary data that is not stored as build-data on all builders. Needs to be used in combination with yieldMetricsValue (see Using StatsService.yieldMetricsValue). Takes the following arguments:

data_name: The name of data to be captured. Same as in yieldMetricsValue.
callback=None: The callback function for this class. This callback receives the data sent to yieldMetricsValue as post_data (see Using StatsService.yieldMetricsValue). It must return a string that is to be sent to the storage backends for storage.

Using `StatsService.yieldMetricsValue`

Advanced users can modify BuildSteps to use StatsService.yieldMetricsValue which will send arbitrary data for storage to the StatsService. It takes the following arguments:

data_name
The name of the data being sent or storage.

post_data
A dictionary of key value pair that is sent for storage. The keys will act as columns in a database and the value is stored under that column.

buildid
The integer build id of the current build. Obtainable in all BuildSteps.

Along with using yieldMetricsValue, the user will also need to use the CaptureData capture class. As an example, we can add the following to a build step:

yieldMetricsValue('test_data_name', {'some_data': 'some_value'}, buildid)

Then, we can add in the master configuration a capture class like this:

captures = [CaptureBuildData('test_data_name', 'Builder1')]

Pass this captures list to a storage backend (as shown in the example at the top of this section) for capturing this data.

Storage Backends

Storage backends are responsible for storing any statistics data sent to them. A storage backend will generally be some sort of a database-server running on a machine. (Note: This machine may be different from the one running BuildMaster)

Currently, only InfluxDB is supported as a storage backend.

class buildbot.statistics.storage_backends.influxdb_client.InfluxStorageService

This class is a Buildbot client to the InfluxDB storage backend. InfluxDB is a distributed, time series database that employs a key-value pair storage system.

It requires the following arguments:

url: The URL where the service is running.
port: The port on which the service is listening.
user: Username of a InfluxDB user.
password: Password for user.
db: The name of database to be used.
captures: A list of objects of Capture Classes. This tells which statistics are to be stored in this storage backend.
name=None: (Optional) The name of this storage backend.

2.5.2.15. `secretsProviders`

See Secret Management for details on secret concepts.

Example usage:

c['secretsProviders'] = [ .. ]

secretsProviders is a list of secrets storage. See Secret Management to configure a secret storage provider.

2.5.2.16. BuildbotNetUsageData 

Since buildbot 0.9.0, buildbot has a simple feature which sends usage analysis info to buildbot.net. This is very important for buildbot developers to understand how the community is using the tools. This allows to better prioritize issues, and understand what plugins are actually being used. This will also be a tool to decide whether to keep support for very old tools. For example buildbot contains support for the venerable CVS, but we have no information whether it actually works beyond the unit tests. We rely on the community to test and report issues with the old features.

With BuildbotNetUsageData, we can know exactly what combination of plugins are working together, how much people are customizing plugins, what versions of the main dependencies people run.

We take your privacy very seriously.

BuildbotNetUsageData will never send information specific to your Code or Intellectual Property. No repository url, shell command values, host names, ip address or custom class names. If it does, then this is a bug, please report.

We still need to track unique number for installation. This is done via doing a sha1 hash of master’s hostname, installation path and fqdn. Using a secure hash means there is no way of knowing hostname, path and fqdn given the hash, but still there is a different hash for each master.

You can see exactly what is sent in the master’s twisted.log. Usage data is sent every time the master is started.

BuildbotNetUsageData can be configured with 4 values:

c['buildbotNetUsageData'] = None disables the feature

c['buildbotNetUsageData'] = 'basic' sends the basic information to buildbot including:

versions of buildbot, python and twisted
platform information (CPU, OS, distribution, python flavor (i.e CPython vs PyPy))
mq and database type (mysql or sqlite?)
www plugins usage
Plugins usages: This counts the number of time each class of buildbot is used in your configuration. This counts workers, builders, steps, schedulers, change sources. If the plugin is subclassed, then it will be prefixed with a >

example of basic report (for the metabuildbot):

{
'versions': {
    'Python': '2.7.6',
    'Twisted': '15.5.0',
    'Buildbot': '0.9.0rc2-176-g5fa9dbf'
},
'platform': {
    'machine': 'x86_64',
    'python_implementation': 'CPython',
    'version': '#140-Ubuntu SMP Mon Jul',
    'processor':
    'x86_64',
    'distro:': ('Ubuntu', '14.04', 'trusty')
    },
'db': 'sqlite',
'mq': 'simple',
'plugins': {
    'buildbot.schedulers.forcesched.ForceScheduler': 2,
    'buildbot.schedulers.triggerable.Triggerable': 1,
    'buildbot.config.BuilderConfig': 4,
    'buildbot.schedulers.basic.AnyBranchScheduler': 2,
    'buildbot.steps.source.git.Git': 4,
    '>>buildbot.steps.trigger.Trigger': 2,
    '>>>buildbot.worker.base.Worker': 4,
    'buildbot.reporters.irc.IRC': 1},
'www_plugins': ['buildbot_travis', 'waterfall_view']
}

c['buildbotNetUsageData'] = 'full' sends the basic information plus additional information:

configuration of each builders: how the steps are arranged together. for example:

{
    'builders': [
        ['buildbot.steps.source.git.Git',
         '>>>buildbot.process.buildstep.BuildStep'],
        ['buildbot.steps.source.git.Git',
         '>>buildbot.steps.trigger.Trigger'],
        ['buildbot.steps.source.git.Git',
         '>>>buildbot.process.buildstep.BuildStep'],
        ['buildbot.steps.source.git.Git',
         '>>buildbot.steps.trigger.Trigger']
    ]
}

c['buildbotNetUsageData'] = myCustomFunction declares a callback to use to specify exactly what to send.

This custom function takes the generated data from full report in the form of a dictionary, and returns a customized report as a jsonable dictionary. You can use this to filter any information you don’t want to disclose. You can also use a custom http_proxy environment variable in order to not send any data while developing your callback.

2.5.2.17. Users Options 

from buildbot.plugins import util
c['user_managers'] = []
c['user_managers'].append(util.CommandlineUserManager(username="user",
                                                      passwd="userpw",
                                                      port=9990))

user_managers contains a list of ways to manually manage User Objects within Buildbot (see User Objects). Currently implemented is a commandline tool buildbot user, described at length in user. In the future, a web client will also be able to manage User Objects and their attributes.

As shown above, to enable the buildbot user tool, you must initialize a CommandlineUserManager instance in your master.cfg. CommandlineUserManager instances require the following arguments:

username: This is the username that will be registered on the PB connection and need to be used when calling buildbot user.
passwd: This is the passwd that will be registered on the PB connection and need to be used when calling buildbot user.
port: The PB connection port must be different than c[‘protocols’][‘pb’][‘port’] and be specified when calling buildbot user

2.5.2.18. Input Validation 

import re
c['validation'] = {
    'branch' : re.compile(r'^[\w.+/~-]*$'),
    'revision' : re.compile(r'^[ \w\.\-\/]*$'),
    'property_name' : re.compile(r'^[\w\.\-\/\~:]*$'),
    'property_value' : re.compile(r'^[\w\.\-\/\~:]*$'),
}

This option configures the validation applied to user inputs of various types. This validation is important since these values are often included in command-line arguments executed on workers. Allowing arbitrary input from untrusted users may raise security concerns.

The keys describe the type of input validated; the values are compiled regular expressions against which the input will be matched. The defaults for each type of input are those given in the example, above.

2.5.2.19. Revision Links 

The revlink parameter is used to create links from revision IDs in the web status to a web-view of your source control system. The parameter’s value must be a callable.

By default, Buildbot is configured to generate revlinks for a number of open source hosting platforms (https://github.com, https://sourceforge.net and https://bitbucket.org).

The callable takes the revision id and repository argument, and should return a URL to the revision. Note that the revision id may not always be in the form you expect, so code defensively. In particular, a revision of “??” may be supplied when no other information is available.

Note that SourceStamps that are not created from version-control changes (e.g., those created by a Nightly or Periodic scheduler) may have an empty repository string if the repository is not known to the scheduler.

Revision Link Helpers

Buildbot provides two helpers for generating revision links. buildbot.revlinks.RevlinkMatcher takes a list of regular expressions and a replacement text. The regular expressions should all have the same number of capture groups. The replacement text should have sed-style references to that capture groups (i.e. ‘1’ for the first capture group), and a single ‘%s’ reference for the revision ID. The repository given is tried against each regular expression in turn. The results are then substituted into the replacement text, along with the revision ID, to obtain the revision link.

from buildbot.plugins import util
c['revlink'] = util.RevlinkMatch([r'git://notmuchmail.org/git/(.*)'],
                                  r'http://git.notmuchmail.org/git/\1/commit/%s')

buildbot.revlinks.RevlinkMultiplexer takes a list of revision link callables, and tries each in turn, returning the first successful match.

2.5.2.20. Codebase Generator 

all_repositories = {
    r'https://hg/hg/mailsuite/mailclient': 'mailexe',
    r'https://hg/hg/mailsuite/mapilib': 'mapilib',
    r'https://hg/hg/mailsuite/imaplib': 'imaplib',
    r'https://github.com/mailinc/mailsuite/mailclient': 'mailexe',
    r'https://github.com/mailinc/mailsuite/mapilib': 'mapilib',
    r'https://github.com/mailinc/mailsuite/imaplib': 'imaplib',
}

def codebaseGenerator(chdict):
    return all_repositories[chdict['repository']]

c['codebaseGenerator'] = codebaseGenerator

For any incoming change, the codebase is set to ‘’. This codebase value is sufficient if all changes come from the same repository (or clones). If changes come from different repositories, extra processing will be needed to determine the codebase for the incoming change. This codebase will then be a logical name for the combination of repository and or branch etc.

The codebaseGenerator accepts a change dictionary as produced by the buildbot.db.changes.ChangesConnectorComponent, with a changeid equal to None.

2.5.3. Change Sources and Changes

A change source is the mechanism which is used by Buildbot to get information about new changes in a repository maintained by a Version Control System.

These change sources fall broadly into two categories: pollers which periodically check the repository for updates; and hooks, where the repository is configured to notify Buildbot whenever an update occurs.

A Change is an abstract way that Buildbot uses to represent changes in any of the Version Control Systems it supports. It contains just enough information needed to acquire specific version of the tree when needed. This usually happens as one of the first steps in a Build.

This concept does not map perfectly to every version control system. For example, for CVS, Buildbot must guess that version updates made to multiple files within a short time represent a single change.

Changes can be provided by a variety of ChangeSource types, although any given project will typically have only a single ChangeSource active.

2.5.3.1. How Different VC Systems Specify Sources 

For CVS, the static specifications are repository and module. In addition to those, each build uses a timestamp (or omits the timestamp to mean the latest) and branch tag (which defaults to HEAD). These parameters collectively specify a set of sources from which a build may be performed.

Subversion combines the repository, module, and branch into a single Subversion URL parameter. Within that scope, source checkouts can be specified by a numeric revision number (a repository-wide monotonically-increasing marker, such that each transaction that changes the repository is indexed by a different revision number), or a revision timestamp. When branches are used, the repository and module form a static baseURL, while each build has a revision number and a branch (which defaults to a statically-specified defaultBranch). The baseURL and branch are simply concatenated together to derive the repourl to use for the checkout.

Perforce is similar. The server is specified through a P4PORT parameter. Module and branch are specified in a single depot path, and revisions are depot-wide. When branches are used, the p4base and defaultBranch are concatenated together to produce the depot path.

Bzr (which is a descendant of Arch/Bazaar, and is frequently referred to as “Bazaar”) has the same sort of repository-vs-workspace model as Arch, but the repository data can either be stored inside the working directory or kept elsewhere (either on the same machine or on an entirely different machine). For the purposes of Buildbot (which never commits changes), the repository is specified with a URL and a revision number.

The most common way to obtain read-only access to a bzr tree is via HTTP, simply by making the repository visible through a web server like Apache. Bzr can also use FTP and SFTP servers, if the worker process has sufficient privileges to access them. Higher performance can be obtained by running a special Bazaar-specific server. None of these matter to the buildbot: the repository URL just has to match the kind of server being used. The repoURL argument provides the location of the repository.

Branches are expressed as subdirectories of the main central repository, which means that if branches are being used, the BZR step is given a baseURL and defaultBranch instead of getting the repoURL argument.

Darcs doesn’t really have the notion of a single master repository. Nor does it really have branches. In Darcs, each working directory is also a repository, and there are operations to push and pull patches from one of these repositories to another. For the Buildbot’s purposes, all you need to do is specify the URL of a repository that you want to build from. The worker will then pull the latest patches from that repository and build them. Multiple branches are implemented by using multiple repositories (possibly living on the same server).

Builders which use Darcs therefore have a static repourl which specifies the location of the repository. If branches are being used, the source Step is instead configured with a baseURL and a defaultBranch, and the two strings are simply concatenated together to obtain the repository’s URL. Each build then has a specific branch which replaces defaultBranch, or just uses the default one. Instead of a revision number, each build can have a context, which is a string that records all the patches that are present in a given tree (this is the output of darcs changes --context, and is considerably less concise than, e.g. Subversion’s revision number, but the patch-reordering flexibility of Darcs makes it impossible to provide a shorter useful specification).

Mercurial follows a decentralized model, and each repository can have several branches and tags. The source Step is configured with a static repourl which specifies the location of the repository. Branches are configured with the defaultBranch argument. The revision is the hash identifier returned by hg identify.

Git also follows a decentralized model, and each repository can have several branches and tags. The source Step is configured with a static repourl which specifies the location of the repository. In addition, an optional branch parameter can be specified to check out code from a specific branch instead of the default master branch. The revision is specified as a SHA1 hash as returned by e.g. git rev-parse. No attempt is made to ensure that the specified revision is actually a subset of the specified branch.

Monotone is another that follows a decentralized model where each repository can have several branches and tags. The source Step is configured with static repourl and branch parameters, which specifies the location of the repository and the branch to use. The revision is specified as a SHA1 hash as returned by e.g. mtn automate select w:. No attempt is made to ensure that the specified revision is actually a subset of the specified branch.

Comparison 

Name	Change	Revision	Branches
CVS	patch [1]	timestamp	unnamed
Subversion	revision	integer	directories
Git	commit	sha1 hash	named refs
Mercurial	changeset	sha1 hash	different repos or (permanently) named commits
Darcs	?	none [2]	different repos
Bazaar	?	?	?
Perforce	?	?	?
BitKeeper	changeset	?	different repos

[1] note that CVS only tracks patches to individual files. Buildbot tries to recognize coordinated changes to multiple files by correlating change times.
[2] Darcs does not have a concise way of representing a particular revision of the source.

Tree Stability 

Changes tend to arrive at a buildmaster in bursts. In many cases, these bursts of changes are meant to be taken together. For example, a developer may have pushed multiple commits to a DVCS that comprise the same new feature or bugfix. To avoid trying to build every change, Buildbot supports the notion of tree stability, by waiting for a burst of changes to finish before starting to schedule builds. This is implemented as a timer, with builds not scheduled until no changes have occurred for the duration of the timer.

2.5.3.2. Choosing a Change Source 

There are a variety of ChangeSource classes available, some of which are meant to be used in conjunction with other tools to deliver Change events from the VC repository to the buildmaster.

As a quick guide, here is a list of VC systems and the ChangeSources that might be useful with them. Note that some of these modules are in Buildbot’s master/contrib directory, meaning that they have been offered by other users in hopes they may be useful, and might require some additional work to make them functional.

CVS

CVSMaildirSource (watching mail sent by master/contrib/buildbot_cvs_mail.py script)
PBChangeSource (listening for connections from buildbot sendchange run in a loginfo script)
PBChangeSource (listening for connections from a long-running master/contrib/viewcvspoll.py polling process which examines the ViewCVS database directly)
Change Hooks in WebStatus

SVN

PBChangeSource (listening for connections from master/contrib/svn_buildbot.py run in a postcommit script)
PBChangeSource (listening for connections from a long-running master/contrib/svn_watcher.py or master/contrib/svnpoller.py polling process
SVNCommitEmailMaildirSource (watching for email sent by commit-email.pl)
SVNPoller (polling the SVN repository)
Change Hooks in WebStatus

Darcs

PBChangeSource (listening for connections from master/contrib/darcs_buildbot.py in a commit script)
Change Hooks in WebStatus

Mercurial

Change Hooks in WebStatus (including master/contrib/hgbuildbot.py, configurable in a changegroup hook)
BitBucket change hook (specifically designed for BitBucket notifications, but requiring a publicly-accessible WebStatus)
HgPoller (polling a remote Mercurial repository)
BitbucketPullrequestPoller (polling Bitbucket for pull requests)
Mail-parsing ChangeSources, though there are no ready-to-use recipes

Bzr (the newer Bazaar)

PBChangeSource (listening for connections from master/contrib/bzr_buildbot.py run in a post-change-branch-tip or commit hook)
BzrPoller (polling the Bzr repository)
Change Hooks in WebStatus

Git

PBChangeSource (listening for connections from master/contrib/git_buildbot.py run in the post-receive hook)
PBChangeSource (listening for connections from master/contrib/github_buildbot.py, which listens for notifications from GitHub)
Change Hooks in WebStatus
GitHub change hook (specifically designed for GitHub notifications, but requiring a publicly-accessible WebStatus)
BitBucket change hook (specifically designed for BitBucket notifications, but requiring a publicly-accessible WebStatus)
GitPoller (polling a remote Git repository)
GitHubPullrequestPoller (polling GitHub API for pull requests)
BitbucketPullrequestPoller (polling Bitbucket for pull requests)

Repo/Gerrit

GerritChangeSource connects to Gerrit via SSH and optionally HTTP to get a live stream of changes
GerritEventLogPoller connects to Gerrit via HTTP with the help of the plugin events-log

Monotone

PBChangeSource (listening for connections from monotone-buildbot.lua, which is available with Monotone)

All VC systems can be driven by a PBChangeSource and the buildbot sendchange tool run from some form of commit script. If you write an email parsing function, they can also all be driven by a suitable mail-parsing source. Additionally, handlers for web-based notification (i.e. from GitHub) can be used with WebStatus’ change_hook module. The interface is simple, so adding your own handlers (and sharing!) should be a breeze.

See Change Source Index for a full list of change sources.

2.5.3.3. Configuring Change Sources 

The change_source configuration key holds all active change sources for the configuration.

Most configurations have a single ChangeSource, watching only a single tree, e.g.,

from buildbot.plugins import changes

c['change_source'] = changes.PBChangeSource()

For more advanced configurations, the parameter can be a list of change sources:

source1 = ...
source2 = ...
c['change_source'] = [
    source1, source2
]

Repository and Project 

ChangeSources will, in general, automatically provide the proper repository attribute for any changes they produce. For systems which operate on URL-like specifiers, this is a repository URL. Other ChangeSources adapt the concept as necessary.

Many ChangeSources allow you to specify a project, as well. This attribute is useful when building from several distinct codebases in the same buildmaster: the project string can serve to differentiate the different codebases. Schedulers can filter on project, so you can configure different builders to run for each project.

2.5.3.4. Mail-parsing ChangeSources 

Many projects publish information about changes to their source tree by sending an email message out to a mailing list, frequently named PROJECT-commits or PROJECT-changes. Each message usually contains a description of the change (who made the change, which files were affected) and sometimes a copy of the diff. Humans can subscribe to this list to stay informed about what’s happening to the source tree.

Buildbot can also subscribe to a -commits mailing list, and can trigger builds in response to Changes that it hears about. The buildmaster admin needs to arrange for these email messages to arrive in a place where the buildmaster can find them, and configure the buildmaster to parse the messages correctly. Once that is in place, the email parser will create Change objects and deliver them to the schedulers (see Schedulers) just like any other ChangeSource.

There are two components to setting up an email-based ChangeSource. The first is to route the email messages to the buildmaster, which is done by dropping them into a maildir. The second is to actually parse the messages, which is highly dependent upon the tool that was used to create them. Each VC system has a collection of favorite change-emailing tools with a slightly different format and its own parsing function. Buildbot has a separate ChangeSource variant for each of these parsing functions.

Once you’ve chosen a maildir location and a parsing function, create the change source and put it in change_source:

from buildbot.plugins import changes

c['change_source'] = changes.CVSMaildirSource("~/maildir-buildbot",
                                              prefix="/trunk/")

Subscribing the Buildmaster 

The recommended way to install Buildbot is to create a dedicated account for the buildmaster. If you do this, the account will probably have a distinct email address (perhaps buildmaster@example.org). Then just arrange for this account’s email to be delivered to a suitable maildir (described in the next section).

If Buildbot does not have its own account, extension addresses can be used to distinguish between emails intended for the buildmaster and emails intended for the rest of the account. In most modern MTAs, the e.g. foo@example.org account has control over every email address at example.org which begins with “foo”, such that emails addressed to account-foo@example.org can be delivered to a different destination than account-bar@example.org. qmail does this by using separate .qmail files for the two destinations (.qmail-foo and .qmail-bar, with .qmail controlling the base address and .qmail-default controlling all other extensions). Other MTAs have similar mechanisms.

Thus you can assign an extension address like foo-buildmaster@example.org to the buildmaster and retain foo@example.org for your own use.

Using Maildirs 

A maildir is a simple directory structure originally developed for qmail that allows safe atomic update without locking. Create a base directory with three subdirectories: new, tmp, and cur. When messages arrive, they are put into a uniquely-named file (using pids, timestamps, and random numbers) in tmp. When the file is complete, it is atomically renamed into new. Eventually the buildmaster notices the file in new, reads and parses the contents, then moves it into cur. A cronjob can be used to delete files in cur at leisure.

Maildirs are frequently created with the maildirmake tool, but a simple mkdir -p ~/MAILDIR/cur,new,tmp is pretty much equivalent.

Many modern MTAs can deliver directly to maildirs. The usual .forward or .procmailrc syntax is to name the base directory with a trailing slash, so something like ~/MAILDIR/. qmail and postfix are maildir-capable MTAs, and procmail is a maildir-capable MDA (Mail Delivery Agent).

Here is an example procmail config, located in ~/.procmailrc:

# .procmailrc
# routes incoming mail to appropriate mailboxes
PATH=/usr/bin:/usr/local/bin
MAILDIR=$HOME/Mail
LOGFILE=.procmail_log
SHELL=/bin/sh

:0
*
new

If procmail is not setup on a system wide basis, then the following one-line .forward file will invoke it.

!/usr/bin/procmail

For MTAs which cannot put files into maildirs directly, the safecat tool can be executed from a .forward file to accomplish the same thing.

The Buildmaster uses the linux DNotify facility to receive immediate notification when the maildir’s new directory has changed. When this facility is not available, it polls the directory for new messages, every 10 seconds by default.

Parsing Email Change Messages 

The second component to setting up an email-based ChangeSource is to parse the actual notices. This is highly dependent upon the VC system and commit script in use.

A couple of common tools used to create these change emails, along with the Buildbot tools to parse them, are:

CVS

Buildbot CVS MailNotifier: CVSMaildirSource

SVN

svnmailer: http://opensource.perlig.de/en/svnmailer/
commit-email.pl: SVNCommitEmailMaildirSource

Bzr

Launchpad: BzrLaunchpadEmailMaildirSource

Mercurial

NotifyExtension: https://www.mercurial-scm.org/wiki/NotifyExtension

Git

post-receive-email: http://git.kernel.org/?p=git/git.git;a=blob;f=contrib/hooks/post-receive-email;hb=HEAD

The following sections describe the parsers available for each of these tools.

Most of these parsers accept a prefix= argument, which is used to limit the set of files that the buildmaster pays attention to. This is most useful for systems like CVS and SVN which put multiple projects in a single repository (or use repository names to indicate branches). Each filename that appears in the email is tested against the prefix: if the filename does not start with the prefix, the file is ignored. If the filename does start with the prefix, that prefix is stripped from the filename before any further processing is done. Thus the prefix usually ends with a slash.

CVSMaildirSource 

class buildbot.changes.mail.CVSMaildirSource

This parser works with the master/contrib/buildbot_cvs_mail.py script.

The script sends an email containing all the files submitted in one directory. It is invoked by using the CVSROOT/loginfo facility.

The Buildbot’s CVSMaildirSource knows how to parse these messages and turn them into Change objects. It takes the directory name of the maildir root. For example:

from buildbot.plugins import changes

c['change_source'] = changes.CVSMaildirSource("/home/buildbot/Mail")

Configuration of CVS and buildbot_cvs_mail.py 

CVS must be configured to invoke the buildbot_cvs_mail.py script when files are checked in. This is done via the CVS loginfo configuration file.

To update this, first do:

cvs checkout CVSROOT

cd to the CVSROOT directory and edit the file loginfo, adding a line like:

SomeModule /cvsroot/CVSROOT/buildbot_cvs_mail.py --cvsroot :ext:example.com:/cvsroot -e buildbot -P SomeModule %@{sVv@}

Note

For cvs version 1.12.x, the --path %p option is required. Version 1.11.x and 1.12.x report the directory path differently.

The above example you put the buildbot_cvs_mail.py script under /cvsroot/CVSROOT. It can be anywhere. Run the script with --help to see all the options. At the very least, the options -e (email) and -P (project) should be specified. The line must end with %{sVv}. This is expanded to the files that were modified.

Additional entries can be added to support more modules.

See buildbot_cvs_mail.py --help for more information on the available options.

SVNCommitEmailMaildirSource 

class buildbot.changes.mail.SVNCommitEmailMaildirSource

SVNCommitEmailMaildirSource parses message sent out by the commit-email.pl script, which is included in the Subversion distribution.

It does not currently handle branches: all of the Change objects that it creates will be associated with the default (i.e. trunk) branch.

from buildbot.plugins import changes

c['change_source'] = changes.SVNCommitEmailMaildirSource("~/maildir-buildbot")

BzrLaunchpadEmailMaildirSource 

class buildbot.changes.mail.BzrLaunchpadEmailMaildirSource

BzrLaunchpadEmailMaildirSource parses the mails that are sent to addresses that subscribe to branch revision notifications for a bzr branch hosted on Launchpad.

The branch name defaults to lp:Launchpad path. For example lp:~maria-captains/maria/5.1.

If only a single branch is used, the default branch name can be changed by setting defaultBranch.

For multiple branches, pass a dictionary as the value of the branchMap option to map specific repository paths to specific branch names (see example below). The leading lp: prefix of the path is optional.

The prefix option is not supported (it is silently ignored). Use the branchMap and defaultBranch instead to assign changes to branches (and just do not subscribe the Buildbot to branches that are not of interest).

The revision number is obtained from the email text. The bzr revision id is not available in the mails sent by Launchpad. However, it is possible to set the bzr append_revisions_only option for public shared repositories to avoid new pushes of merges changing the meaning of old revision numbers.

from buildbot.plugins import changes

bm = {
    'lp:~maria-captains/maria/5.1': '5.1',
    'lp:~maria-captains/maria/6.0': '6.0'
}
c['change_source'] = changes.BzrLaunchpadEmailMaildirSource("~/maildir-buildbot",
                                                            branchMap=bm)

2.5.3.5. PBChangeSource 

class buildbot.changes.pb.PBChangeSource

PBChangeSource actually listens on a TCP port for clients to connect and push change notices into the Buildmaster. This is used by the built-in buildbot sendchange notification tool, as well as several version-control hook scripts. This change is also useful for creating new kinds of change sources that work on a push model instead of some kind of subscription scheme, for example a script which is run out of an email .forward file. This ChangeSource always runs on the same TCP port as the workers. It shares the same protocol, and in fact shares the same space of “usernames”, so you cannot configure a PBChangeSource with the same name as a worker.

If you have a publicly accessible worker port and are using PBChangeSource, you must establish a secure username and password for the change source. If your sendchange credentials are known (e.g., the defaults), then your buildmaster is susceptible to injection of arbitrary changes, which (depending on the build factories) could lead to arbitrary code execution on workers.

The PBChangeSource is created with the following arguments.

port

Which port to listen on. If None (which is the default), it shares the port used for worker connections.

user

The user account that the client program must use to connect. Defaults to change

passwd

The password for the connection - defaults to changepw. Can be a Secret. Do not use this default on a publicly exposed port!

prefix

The prefix to be found and stripped from filenames delivered over the connection, defaulting to None. Any filenames which do not start with this prefix will be removed. If all the filenames in a given Change are removed, then that whole Change will be dropped. This string should probably end with a directory separator.

This is useful for changes coming from version control systems that represent branches as parent directories within the repository (like SVN and Perforce). Use a prefix of trunk/ or project/branches/foobranch/ to only follow one branch and to get correct tree-relative filenames. Without a prefix, the PBChangeSource will probably deliver Changes with filenames like trunk/foo.c instead of just foo.c. Of course this also depends upon the tool sending the Changes in (like buildbot sendchange) and what filenames it is delivering: that tool may be filtering and stripping prefixes at the sending end.

For example:

from buildbot.plugins import changes

c['change_source'] = changes.PBChangeSource(port=9999, user='laura', passwd='fpga')

The following hooks are useful for sending changes to a PBChangeSource:

Bzr Hook 

Bzr is also written in Python, and the Bzr hook depends on Twisted to send the changes.

To install, put master/contrib/bzr_buildbot.py in one of your plugins locations a bzr plugins directory (e.g., ~/.bazaar/plugins). Then, in one of your bazaar conf files (e.g., ~/.bazaar/locations.conf), set the location you want to connect with Buildbot with these keys:

buildbot_on one of ‘commit’, ‘push, or ‘change’. Turns the plugin on to report changes via commit, changes via push, or any changes to the trunk. ‘change’ is recommended.

buildbot_server (required to send to a Buildbot master) the URL of the Buildbot master to which you will connect (as of this writing, the same server and port to which workers connect).

buildbot_port (optional, defaults to 9989) the port of the Buildbot master to which you will connect (as of this writing, the same server and port to which workers connect)

buildbot_pqm (optional, defaults to not pqm) Normally, the user that commits the revision is the user that is responsible for the change. When run in a pqm (Patch Queue Manager, see https://launchpad.net/pqm) environment, the user that commits is the Patch Queue Manager, and the user that committed the parent revision is responsible for the change. To turn on the pqm mode, set this value to any of (case-insensitive) “Yes”, “Y”, “True”, or “T”.

buildbot_dry_run (optional, defaults to not a dry run) Normally, the post-commit hook will attempt to communicate with the configured Buildbot server and port. If this parameter is included and any of (case-insensitive) “Yes”, “Y”, “True”, or “T”, then the hook will simply print what it would have sent, but not attempt to contact the Buildbot master.

buildbot_send_branch_name (optional, defaults to not sending the branch name) If your Buildbot’s bzr source build step uses a repourl, do not turn this on. If your buildbot’s bzr build step uses a baseURL, then you may set this value to any of (case-insensitive) “Yes”, “Y”, “True”, or “T” to have the Buildbot master append the branch name to the baseURL.

Note

The bzr smart server (as of version 2.2.2) doesn’t know how to resolve bzr:// urls into absolute paths so any paths in locations.conf won’t match, hence no change notifications will be sent to Buildbot. Setting configuration parameters globally or in-branch might still work. When Buildbot no longer has a hardcoded password, it will be a configuration option here as well.

Here’s a simple example that you might have in your ~/.bazaar/locations.conf.

[chroot-*:///var/local/myrepo/mybranch]
buildbot_on = change
buildbot_server = localhost

2.5.3.6. P4Source 

The P4Source periodically polls a Perforce depot for changes. It accepts the following arguments:

p4port: The Perforce server to connect to (as host:port).
p4user: The Perforce user.
p4passwd: The Perforce password.
p4base: The base depot path to watch, without the trailing ‘/…’.
p4bin: An optional string parameter. Specify the location of the perforce command line binary (p4). You only need to do this if the perforce binary is not in the path of the Buildbot user. Defaults to p4.
split_file: A function that maps a pathname, without the leading p4base, to a (branch, filename) tuple. The default just returns (None, branchfile), which effectively disables branch support. You should supply a function which understands your repository structure.
pollInterval: How often to poll, in seconds. Defaults to 600 (10 minutes).
pollRandomDelayMin: Minimum delay in seconds to wait before each poll, default is 0. This is useful in case you have a lot of pollers and you want to spread the polling load over a period of time. Setting it equal to the maximum delay will effectively delay all polls by a fixed amount of time. Must be less than or equal to the maximum delay.
pollRandomDelayMax: Maximum delay in seconds to wait before each poll, default is 0. This is useful in case you have a lot of pollers and you want to spread the polling load over a period of time. Must be less than the poll interval.
project: Set the name of the project to be used for the P4Source. This will then be set in any changes generated by the P4Source, and can be used in a Change Filter for triggering particular builders.
pollAtLaunch: Determines when the first poll occurs. True = immediately on launch, False = wait for one pollInterval (default).
histmax: The maximum number of changes to inspect at a time. If more than this number occur since the last poll, older changes will be silently ignored.
encoding: The character encoding of p4's output. This defaults to “utf8”, but if your commit messages are in another encoding, specify that here. For example, if you’re using Perforce on Windows, you may need to use “cp437” as the encoding if “utf8” generates errors in your master log.
server_tz: The timezone of the Perforce server, using the usual timezone format (e.g: "Europe/Stockholm") in case it’s not in UTC.
use_tickets: Set to True to use ticket-based authentication, instead of passwords (but you still need to specify p4passwd).
ticket_login_interval: How often to get a new ticket, in seconds, when use_tickets is enabled. Defaults to 86400 (24 hours).
revlink: A function that maps branch and revision to a valid url (e.g. p4web), stored along with the change. This function must be a callable which takes two arguments, the branch and the revision. Defaults to lambda branch, revision: (u’’)
resolvewho: A function that resolves the Perforce ‘user@workspace’ into a more verbose form, stored as the author of the change. Useful when usernames do not match email addresses and external, client-side lookup is required. This function must be a callable which takes one argument. Defaults to lambda who: (who)

Example #1 

This configuration uses the P4PORT, P4USER, and P4PASSWD specified in the buildmaster’s environment. It watches a project in which the branch name is simply the next path component, and the file is all path components after.

from buildbot.plugins import changes

s = changes.P4Source(p4base='//depot/project/',
                     split_file=lambda branchfile: branchfile.split('/',1))
c['change_source'] = s

Example #2 

Similar to the previous example but also resolves the branch and revision into a valid revlink.

from buildbot.plugins import changes

s = changes.P4Source(
    p4base='//depot/project/',
    split_file=lambda branchfile: branchfile.split('/',1))
    revlink=lambda branch, revision: 'http://p4web:8080/@md=d&@/{}?ac=10'.format(revision)
c['change_source'] = s

2.5.3.7. SVNPoller 

class buildbot.changes.svnpoller.SVNPoller

The SVNPoller is a ChangeSource which periodically polls a Subversion repository for new revisions, by running the svn log command in a subshell. It can watch a single branch or multiple branches.

SVNPoller accepts the following arguments:

repourl

The base URL path to watch, like svn://svn.twistedmatrix.com/svn/Twisted/trunk, or http://divmod.org/svn/Divmo/, or even file:///home/svn/Repository/ProjectA/branches/1.5/. This must include the access scheme, the location of the repository (both the hostname for remote ones, and any additional directory names necessary to get to the repository), and the sub-path within the repository’s virtual filesystem for the project and branch of interest.

The SVNPoller will only pay attention to files inside the subdirectory specified by the complete repourl.

split_file

A function to convert pathnames into (branch, relative_pathname) tuples. Use this to explain your repository’s branch-naming policy to SVNPoller. This function must accept a single string (the pathname relative to the repository) and return a two-entry tuple. Directory pathnames always end with a right slash to distinguish them from files, like trunk/src/, or src/. There are a few utility functions in buildbot.changes.svnpoller that can be used as a split_file function; see below for details.

For directories, the relative pathname returned by split_file should end with a right slash but an empty string is also accepted for the root, like ("branches/1.5.x", "") being converted from "branches/1.5.x/".

The default value always returns (None, path), which indicates that all files are on the trunk.

Subclasses of SVNPoller can override the split_file method instead of using the split_file= argument.

project

Set the name of the project to be used for the SVNPoller. This will then be set in any changes generated by the SVNPoller, and can be used in a Change Filter for triggering particular builders.

svnuser

An optional string parameter. If set, the option –user argument will be added to all svn commands. Use this if you have to authenticate to the svn server before you can do svn info or svn log commands. Can be a Secret.

svnpasswd

Like svnuser, this will cause a option –password argument to be passed to all svn commands. Can be a Secret.

pollInterval

How often to poll, in seconds. Defaults to 600 (checking once every 10 minutes). Lower this if you want the Buildbot to notice changes faster, raise it if you want to reduce the network and CPU load on your svn server. Please be considerate of public SVN repositories by using a large interval when polling them.

pollRandomDelayMin

Minimum delay in seconds to wait before each poll, default is 0. This is useful in case you have a lot of pollers and you want to spread the polling load over a period of time. Setting it equal to the maximum delay will effectively delay all polls by a fixed amount of time. Must be less than or equal to the maximum delay.

pollRandomDelayMax

Maximum delay in seconds to wait before each poll, default is 0. This is useful in case you have a lot of pollers and you want to spread the polling load over a period of time. Must be less than the poll interval.

pollAtLaunch

Determines when the first poll occurs. True = immediately on launch, False = wait for one pollInterval (default).

histmax

The maximum number of changes to inspect at a time. Every pollInterval seconds, the SVNPoller asks for the last histmax changes and looks through them for any revisions it does not already know about. If more than histmax revisions have been committed since the last poll, older changes will be silently ignored. Larger values of histmax will cause more time and memory to be consumed on each poll attempt. histmax defaults to 100.

svnbin

This controls the svn executable to use. If subversion is installed in a weird place on your system (outside of the buildmaster’s PATH), use this to tell SVNPoller where to find it. The default value of svn will almost always be sufficient.

revlinktmpl

This parameter is deprecated in favour of specifying a global revlink option. This parameter allows a link to be provided for each revision (for example, to websvn or viewvc). These links appear anywhere changes are shown, such as on build or change pages. The proper form for this parameter is an URL with the portion that will substitute for a revision number replaced by ‘’%s’’. For example, 'http://myserver/websvn/revision.php?rev=%s' could be used to cause revision links to be created to a websvn repository viewer.

cachepath

If specified, this is a pathname of a cache file that SVNPoller will use to store its state between restarts of the master.

extra_args

If specified, the extra arguments will be added to the svn command args.

Several split file functions are available for common SVN repository layouts. For a poller that is only monitoring trunk, the default split file function is available explicitly as split_file_alwaystrunk:

from buildbot.plugins import changes, util

c['change_source'] = changes.SVNPoller(
    repourl="svn://svn.twistedmatrix.com/svn/Twisted/trunk",
    split_file=util.svn.split_file_alwaystrunk)

For repositories with the /trunk and /branches/BRANCH layout, split_file_branches will do the job:

from buildbot.plugins import changes, util

c['change_source'] = changes.SVNPoller(
    repourl="https://amanda.svn.sourceforge.net/svnroot/amanda/amanda",
    split_file=util.svn.split_file_branches)

When using this splitter the poller will set the project attribute of any changes to the project attribute of the poller.

For repositories with the PROJECT/trunk and PROJECT/branches/BRANCH layout, split_file_projects_branches will do the job:

from buildbot.plugins import changes, util

c['change_source'] = changes.SVNPoller(
    repourl="https://amanda.svn.sourceforge.net/svnroot/amanda/",
    split_file=util.svn.split_file_projects_branches)

When using this splitter the poller will set the project attribute of any changes to the project determined by the splitter.

The SVNPoller is highly adaptable to various Subversion layouts. See Customizing SVNPoller for details and some common scenarios.

2.5.3.8. Bzr Poller 

If you cannot insert a Bzr hook in the server, you can use the BzrPoller. To use it, put master/contrib/bzr_buildbot.py somewhere that your Buildbot configuration can import it. Even putting it in the same directory as the master.cfg should work. Install the poller in the Buildbot configuration as with any other change source. Minimally, provide a URL that you want to poll (bzr://, bzr+ssh://, or lp:), making sure the Buildbot user has necessary privileges.

# put bzr_buildbot.py file to the same directory as master.cfg
from bzr_buildbot import BzrPoller

c['change_source'] = BzrPoller(
    url='bzr://hostname/my_project',
    poll_interval=300)

The BzrPoller parameters are:

url: The URL to poll.
poll_interval: The number of seconds to wait between polls. Defaults to 10 minutes.
branch_name: Any value to be used as the branch name. Defaults to None, or specify a string, or specify the constants from bzr_buildbot.py SHORT or FULL to get the short branch name or full branch address.
blame_merge_author: Normally, the user that commits the revision is the user that is responsible for the change. When run in a pqm (Patch Queue Manager, see https://launchpad.net/pqm) environment, the user that commits is the Patch Queue Manager, and the user that committed the merged, parent revision is responsible for the change. Set this value to True if this is pointed against a PQM-managed branch.

2.5.3.9. GitPoller 

If you cannot take advantage of post-receive hooks as provided by master/contrib/git_buildbot.py for example, then you can use the GitPoller.

The GitPoller periodically fetches from a remote Git repository and processes any changes. It requires its own working directory for operation. The default should be adequate, but it can be overridden via the workdir property.

Note

There can only be a single GitPoller pointed at any given repository.

The GitPoller requires Git-1.7 and later. It accepts the following arguments:

repourl

The git-url that describes the remote repository, e.g. git@example.com:foobaz/myrepo.git (see the git fetch help for more info on git-url formats)

branches

One of the following:

a list of the branches to fetch. Non-existing branches are ignored.
True indicating that all branches should be fetched
a callable which takes a single argument. It should take a remote refspec (such as 'refs/heads/master'), and return a boolean indicating whether that branch should be fetched.

If not provided, GitPoller will use HEAD to fetch the remote default branch.

branch

Accepts a single branch name to fetch. Exists for backwards compatibility with old configurations.

pollInterval

Interval in seconds between polls, default is 10 minutes

pollRandomDelayMin

pollRandomDelayMax

pollAtLaunch

Determines when the first poll occurs. True = immediately on launch, False = wait for one pollInterval (default).

buildPushesWithNoCommits

Determines if a push on a new branch or update of an already known branch with already known commits should trigger a build. This is useful in case you have build steps depending on the name of the branch and you use topic branches for development. When you merge your topic branch into “master” (for instance), a new build will be triggered. (defaults to False).

gitbin

Path to the Git binary, defaults to just 'git'

category

Set the category to be used for the changes produced by the GitPoller. This will then be set in any changes generated by the GitPoller, and can be used in a Change Filter for triggering particular builders.

project

Set the name of the project to be used for the GitPoller. This will then be set in any changes generated by the GitPoller, and can be used in a Change Filter for triggering particular builders.

usetimestamps

Parse each revision’s commit timestamp (default is True), or ignore it in favor of the current time, so that recently processed commits appear together in the waterfall page.

encoding

Set encoding will be used to parse author’s name and commit message. Default encoding is 'utf-8'. This will not be applied to file names since Git will translate non-ascii file names to unreadable escape sequences.

workdir

The directory where the poller should keep its local repository. The default is gitpoller_work. If this is a relative path, it will be interpreted relative to the master’s basedir. Multiple Git pollers can share the same directory.

only_tags

Determines if the GitPoller should poll for new tags in the git repository.

sshPrivateKey (optional)

Specifies private SSH key for git to use. This may be either a Secret or just a string. This option requires Git-2.3 or later. The master must either have the host in the known hosts file or the host key must be specified via the sshHostKey option.

sshHostKey (optional)

Specifies public host key to match when authenticating with SSH public key authentication. This may be either a Secret or just a string. sshPrivateKey must be specified in order to use this option. The host key must be in the form of <key type> <base64-encoded string>, e.g. ssh-rsa AAAAB3N<…>FAaQ==.

sshKnownHosts (optional)

Specifies the contents of the SSH known_hosts file to match when authenticating with SSH public key authentication. This may be either a Secret or just a string. sshPrivateKey must be specified in order to use this option. sshHostKey must not be specified in order to use this option.

A configuration for the Git poller might look like this:

from buildbot.plugins import changes

c['change_source'] = changes.GitPoller(repourl='git@example.com:foobaz/myrepo.git',
                                       branches=['master', 'great_new_feature'])

2.5.3.10. HgPoller 

The HgPoller periodically pulls a named branch from a remote Mercurial repository and processes any changes. It requires its own working directory for operation, which must be specified via the workdir property.

The HgPoller requires a working hg executable, and at least a read-only access to the repository it polls (possibly through ssh keys or by tweaking the hgrc of the system user Buildbot runs as).

The HgPoller will not transmit any change if there are several heads on the watched named branch. This is similar (although not identical) to the Mercurial executable behaviour. This exceptional condition is usually the result of a developer mistake, and usually does not last for long. It is reported in logs. If fixed by a later merge, the buildmaster administrator does not have anything to do: that merge will be transmitted, together with the intermediate ones.

The HgPoller accepts the following arguments:

name

The name of the poller. This must be unique, and defaults to the repourl.

repourl

The url that describes the remote repository, e.g. http://hg.example.com/projects/myrepo. Any url suitable for hg pull can be specified.

bookmarks

A list of the bookmarks to monitor.

branches

A list of the branches to monitor; defaults to ['default'].

branch

The desired branch to pull. Exists for backwards compatibility with old configurations.

workdir

The directory where the poller should keep its local repository. It is mandatory for now, although later releases may provide a meaningful default.

It also serves to identify the poller in the buildmaster internal database. Changing it may result in re-processing all changes so far.

Several HgPoller instances may share the same workdir for mutualisation of the common history between two different branches, thus easing on local and remote system resources and bandwidth.

If relative, the workdir will be interpreted from the master directory.

pollInterval

Interval in seconds between polls, default is 10 minutes

pollRandomDelayMin

pollRandomDelayMax

pollAtLaunch

Determines when the first poll occurs. True = immediately on launch, False = wait for one pollInterval (default).

hgbin

Path to the Mercurial binary, defaults to just 'hg'.

category

Set the category to be used for the changes produced by the HgPoller. This will then be set in any changes generated by the HgPoller, and can be used in a Change Filter for triggering particular builders.

project

Set the name of the project to be used for the HgPoller. This will then be set in any changes generated by the HgPoller, and can be used in a Change Filter for triggering particular builders.

usetimestamps

Parse each revision’s commit timestamp (default is True), or ignore it in favor of the current time, so that recently processed commits appear together in the waterfall page.

encoding

Set encoding will be used to parse author’s name and commit message. Default encoding is 'utf-8'.

revlink

A function that maps branch and revision to a valid url (e.g. hgweb), stored along with the change. This function must be a callable which takes two arguments, the branch and the revision. Defaults to lambda branch, revision: (u’’)

A configuration for the Mercurial poller might look like this:

from buildbot.plugins import changes

c['change_source'] = changes.HgPoller(repourl='http://hg.example.org/projects/myrepo',
                                      branch='great_new_feature',
                                      workdir='hg-myrepo')

2.5.3.11. GitHubPullrequestPoller 

class buildbot.changes.github.GitHubPullrequestPoller

This GitHubPullrequestPoller periodically polls the GitHub API for new or updated pull requests. The author, revision, revlink, branch and files fields in the recorded changes are populated with information extracted from the pull request. This allows to filter for certain changes in files and create a blamelist based on the authors in the GitHub pull request.

The GitHubPullrequestPoller accepts the following arguments:

owner: The owner of the GitHub repository. This argument is required.
repo: The name of the GitHub repository. This argument is required.
branches: List of branches to accept as base branch (e.g. master). Defaults to None and accepts all branches as base.
pollInterval: Poll interval between polls in seconds. Default is 10 minutes.
pollAtLaunch: Whether to poll on startup of the buildbot master. Default is False and first poll will occur pollInterval seconds after the master start.
category: Set the category to be used for the changes produced by the GitHubPullrequestPoller. This will then be set in any changes generated by the GitHubPullrequestPoller, and can be used in a Change Filter for triggering particular builders.
project: Set the name of the project to be used for the GitHubPullrequestPoller. This will then be set in any changes generated by the GitHubPullrequestPoller, and can be used in a Change Filter for triggering particular builders. If unset, the default is to use the full name of the project as returned by the GitHub API.
baseURL: GitHub API endpoint. Default is https://api.github.com.
pullrequest_filter: A callable which takes a dict which contains the decoded JSON object of the GitHub pull request as argument. All fields specified by the GitHub API are accessible. If the callable returns False the pull request is ignored. Default is True which does not filter any pull requests.
token: A GitHub API token to execute all requests to the API authenticated. It is strongly recommended to use a API token since it increases GitHub API rate limits significantly.
repository_type: Set which type of repository link will be in the repository property. Possible values https, svn, git or svn. This link can then be used in a Source Step to checkout the source.
magic_link: Set to True if the changes should contain refs/pulls/<PR #>/merge in the branch property and a link to the base repository in the repository property. These properties can be used by the GitHub source to pull from the special branch in the base repository. Default is False.
github_property_whitelist: A list of fnmatch expressions which match against the flattened pull request information JSON prefixed with github. For example github.number represents the pull request number. Available entries can be looked up in the GitHub API Documentation or by examining the data returned for a pull request by the API.

2.5.3.12. BitbucketPullrequestPoller 

class buildbot.changes.bitbucket.BitbucketPullrequestPoller

This BitbucketPullrequestPoller periodically polls Bitbucket for new or updated pull requests. It uses Bitbuckets powerful Pull Request REST API to gather the information needed.

The BitbucketPullrequestPoller accepts the following arguments:

owner: The owner of the Bitbucket repository. All Bitbucket Urls are of the form https://bitbucket.org/owner/slug/.
slug: The name of the Bitbucket repository.
auth: Authorization data tuple (usename, password) (optional). If set, it will be used as authorization headers at Bitbucket API.
branch: A single branch or a list of branches which should be processed. If it is None (the default) all pull requests are used.
pollInterval: Interval in seconds between polls, default is 10 minutes.
pollAtLaunch: Determines when the first poll occurs. True = immediately on launch, False = wait for one pollInterval (default).
category: Set the category to be used by the BitbucketPullrequestPoller. This will then be set in any changes generated by the BitbucketPullrequestPoller, and can be used in a Change Filter for triggering particular builders.
project: Set the name of the project to be used by the BitbucketPullrequestPoller. This will then be set in any changes generated by the BitbucketPullrequestPoller, and can be used in a Change Filter for triggering particular builders.
pullrequest_filter: A callable which takes one parameter, the decoded Python object of the pull request JSON. If it returns False, the pull request is ignored. It can be used to define custom filters based on the content of the pull request. See the Bitbucket documentation for more information about the format of the response. By default, the filter always returns True.
usetimestamps: Parse each revision’s commit timestamp (default is True), or ignore it in favor of the current time, so that recently processed commits appear together in the waterfall page.
bitbucket_property_whitelist: A list of fnmatch expressions which match against the flattened pull request information JSON prefixed with bitbucket. For example bitbucket.id represents the pull request ID. Available entries can be looked up in the BitBucket API Documentation or by examining the data returned for a pull request by the API.
encoding: This parameter is deprecated and has no effects. Author’s name and commit message are always parsed in 'utf-8'.

A minimal configuration for the Bitbucket pull request poller might look like this:

from buildbot.plugins import changes

c['change_source'] = changes.BitbucketPullrequestPoller(
    owner='myname',
    slug='myrepo',
  )

Here is a more complex configuration using a pullrequest_filter. The pull request is only processed if at least 3 people have already approved it:

def approve_filter(pr, threshold):
    approves = 0
    for participant in pr['participants']:
        if participant['approved']:
            approves = approves + 1

    if approves < threshold:
        return False
    return True

from buildbot.plugins import changes
c['change_source'] = changes.BitbucketPullrequestPoller(
    owner='myname',
    slug='myrepo',
    branch='mybranch',
    project='myproject',
    pullrequest_filter=lambda pr : approve_filter(pr,3),
    pollInterval=600,
)

Warning

Anyone who can create pull requests for the Bitbucket repository can initiate a change, potentially causing the buildmaster to run arbitrary code.

2.5.3.13. GerritChangeSource 

class buildbot.changes.gerritchangesource.GerritChangeSource

The GerritChangeSource class connects to a Gerrit server by its SSH interface and uses its event source mechanism, gerrit stream-events.

Optionally it may use the events-log plugin to retrieve any events that occur while Buildbot is not connected. If events-log mechanism is not used any events that occur while buildbot is not connected to Gerrit will be lost.

Note

The GerritChangeSource requires either the txrequest or the treq package for using the HTTP API.

The GerritChangeSource accepts the following arguments:

gerritserver: The dns or ip that host the Gerrit ssh server
gerritport: The port of the Gerrit ssh server
username: The username to use to connect to Gerrit
identity_file: Ssh identity file to for authentication (optional). Pay attention to the ssh passphrase
handled_events: Event to be handled (optional). By default processes patchset-created and ref-updated
get_files: Populate the files attribute of emitted changes (default False). Buildbot will run an extra query command for each handled event to determine the changed files.
ssh_server_alive_interval_s: Sets the ServerAliveInterval option of the ssh client (default 15). This causes client to emit periodic keepalive messages in case the connection is not otherwise active. If the server does not respond at least ssh_server_alive_count_max times, a reconnection is forced. This helps to avoid stuck connections in case network link is severed without notification in the TCP layer. Specifying None will omit the option from the ssh client command line.
ssh_server_alive_count_max: Sets the ServerAliveCountMax option of the ssh client (default 3). If the server does not respond at least ssh_server_alive_count_max times, a reconnection is forced. This helps to avoid stuck connections in case network link is severed without notification in the TCP layer. Specifying None will omit the option from the ssh client command line.
http_url: (optional) HTTP URL to use when fetching events from the Gerrit internal database. This is used to fill in events that have occurred when Buildbot was not connected to the SSH API. If the URL of the events-log endpoint for your server is https://example.com/a/plugins/events-log/events/ then the http_url is https://example.com.
http_auth: (optional) authentication credentials for events-log plugin. If Gerrit is configured with BasicAuth, then it shall be ('login', 'password'). If Gerrit is configured with DigestAuth, then it shall be requests.auth.HTTPDigestAuth('login', 'password') from the requests module. However, note that usage of requests.auth.HTTPDigestAuth is incompatible with treq.
http_poll_interval: (optional) frequency to poll the HTTP API when events are not being received through the SSH connection. The default is 30 seconds.
debug: Print Gerrit event in the log (default False). This allows to debug event content, but will eventually fill your logs with useless Gerrit event logs.

By default this class adds a change to the Buildbot system for each of the following events:

patchset-created: A change is proposed for review. Automatic checks like checkpatch.pl can be automatically triggered. Beware of what kind of automatic task you trigger. At this point, no trusted human has reviewed the code, and a patch could be specially crafted by an attacker to compromise your workers.
ref-updated: A change has been merged into the repository. Typically, this kind of event can lead to a complete rebuild of the project, and upload binaries to an incremental build results server.

But you can specify how to handle events:

Any event with change and patchSet will be processed by universal collector by default.
In case you’ve specified processing function for the given kind of events, all events of this kind will be processed only by this function, bypassing universal collector.

An example:

from buildbot.plugins import changes

class MyGerritChangeSource(changes.GerritChangeSource):
    """Custom GerritChangeSource
    """
    def eventReceived_patchset_created(self, properties, event):
        """Handler events without properties
        """
        properties = {}
        self.addChangeFromEvent(properties, event)

This class will populate the property list of the triggered build with the info received from Gerrit server in JSON format.

Warning

If you selected GerritChangeSource, you must use Gerrit source step: the branch property of the change will be target_branch/change_id and such a ref cannot be resolved, so the Git source step would fail.

In case of patchset-created event, these properties will be:

event.change.branch: Branch of the Change
event.change.id: Change’s ID in the Gerrit system (the ChangeId: in commit comments)
event.change.number: Change’s number in Gerrit system
event.change.owner.email: Change’s owner email (owner is first uploader)
event.change.owner.name: Change’s owner name
event.change.project: Project of the Change
event.change.subject: Change’s subject
event.change.url: URL of the Change in the Gerrit’s web interface
event.patchSet.number: Patchset’s version number
event.patchSet.ref: Patchset’s Gerrit “virtual branch”
event.patchSet.revision: Patchset’s Git commit ID
event.patchSet.uploader.email: Patchset uploader’s email (owner is first uploader)
event.patchSet.uploader.name: Patchset uploader’s name (owner is first uploader)
event.type: Event type (patchset-created)
event.uploader.email: Patchset uploader’s email
event.uploader.name: Patchset uploader’s name

In case of ref-updated event, these properties will be:

event.refUpdate.newRev: New Git commit ID (after merger)
event.refUpdate.oldRev: Previous Git commit ID (before merger)
event.refUpdate.project: Project that was updated
event.refUpdate.refName: Branch that was updated
event.submitter.email: Submitter’s email (merger responsible)
event.submitter.name: Submitter’s name (merger responsible)
event.type: Event type (ref-updated)
event.submitter.email: Submitter’s email (merger responsible)
event.submitter.name: Submitter’s name (merger responsible)

A configuration for this source might look like:

from buildbot.plugins import changes

c['change_source'] = changes.GerritChangeSource(
    "gerrit.example.com",
    "gerrit_user",
    handled_events=["patchset-created", "change-merged"])

See master/docs/examples/git_gerrit.cfg or master/docs/examples/repo_gerrit.cfg in the Buildbot distribution for a full example setup of Git+Gerrit or Repo+Gerrit of GerritChangeSource.

2.5.3.14. GerritEventLogPoller 

class buildbot.changes.gerritchangesource.GerritEventLogPoller

The GerritEventLogPoller class is similar to GerritChangeSource and connects to the Gerrit server only by its HTTP interface and uses the events-log plugin.

Note

The GerritEventLogPoller requires either the txrequest or the treq package.

The GerritEventLogPoller accepts the following arguments:

baseURL: The HTTP url where to find Gerrit. If the URL of the events-log endpoint for your server is https://example.com/a/plugins/events-log/events/ then the baseURL is https://example.com/a. Ensure that /a is included.
auth: A request’s authentication configuration. If Gerrit is configured with BasicAuth, then it shall be ('login', 'password'). If Gerrit is configured with DigestAuth, then it shall be requests.auth.HTTPDigestAuth('login', 'password') from the requests module. However, note that usage of requests.auth.HTTPDigestAuth is incompatible with treq.
handled_events: Event to be handled (optional). By default processes patchset-created and ref-updated.
pollInterval: Interval in seconds between polls (default is 30 sec).
pollAtLaunch: Determines when the first poll occurs. True = immediately on launch (default), False = wait for one pollInterval.
gitBaseURL: The git URL where Gerrit is accessible via git+ssh protocol.
get_files: Populate the files attribute of emitted changes (default False). Buildbot will run an extra query command for each handled event to determine the changed files.
debug: Print Gerrit event in the log (default False). This allows to debug event content, but will eventually fill your logs with useless Gerrit event logs.

The same customization can be done as GerritChangeSource for handling special events.

2.5.3.15. GerritChangeFilter 

class buildbot.changes.gerritchangesource.GerritChangeFilter

GerritChangeFilter is a ready to use ChangeFilter you can pass to AnyBranchScheduler in order to filter changes, to create pre-commit builders or post-commit schedulers. It has the same api as Change Filter, except it has additional eventtype set of filter (can as well be specified as value, list, regular expression, or callable).

An example is following:

from buildbot.plugins import schedulers, util

# this scheduler will create builds when a patch is uploaded to gerrit
# but only if it is uploaded to the "main" branch
schedulers.AnyBranchScheduler(
    name="main-precommit",
    change_filter=util.GerritChangeFilter(branch="main", eventtype="patchset-created"),
    treeStableTimer=15*60,
    builderNames=["main-precommit"])

# this scheduler will create builds when a patch is merged in the "main" branch
# for post-commit tests
schedulers.AnyBranchScheduler(name="main-postcommit",
                              change_filter=util.GerritChangeFilter("main", "ref-updated"),
                              treeStableTimer=15*60,
                              builderNames=["main-postcommit"])

2.5.3.16. Change Hooks (HTTP Notifications)

Buildbot already provides a web frontend, and that frontend can easily be used to receive HTTP push notifications of commits from services like GitHub. See Change Hooks for more information.

2.5.4. Changes

class buildbot.changes.changes.Change

A Change is an abstract way Buildbot uses to represent a single change to the source files performed by a developer. In version control systems that support the notion of atomic check-ins, a change represents a changeset or commit. Instances of Change have the following attributes.

2.5.4.1. Who

Each Change has a who attribute, which specifies which developer is responsible for the change. This is a string which comes from a namespace controlled by the VC repository. Frequently this means it is a username on the host which runs the repository, but not all VC systems require this. Each StatusNotifier will map the who attribute into something appropriate for their particular means of communication: an email address, an IRC handle, etc.

This who attribute is also parsed and stored into Buildbot’s database (see User Objects). Currently, only who attributes in Changes from git repositories are translated into user objects, but in the future all incoming Changes will have their who parsed and stored.

2.5.4.2. Files

It also has a list of files, which are just the tree-relative filenames of any files that were added, deleted, or modified for this Change. These filenames are checked by the fileIsImportant function of a scheduler to decide whether it should trigger a new build or not. For example, the scheduler could use the following function to only run a build if a C file was checked in:

def has_C_files(change):
    for name in change.files:
        if name.endswith(".c"):
            return True
    return False

Certain BuildSteps can also use the list of changed files to run a more targeted series of tests, e.g. the python_twisted.Trial step can run just the unit tests that provide coverage for the modified .py files instead of running the full test suite.

2.5.4.3. Comments

The Change also has a comments attribute, which is a string containing any checkin comments.

2.5.4.4. Project

The project attribute of a change or source stamp describes the project to which it corresponds, as a short human-readable string. This is useful in cases where multiple independent projects are built on the same buildmaster. In such cases, it can be used to control which builds are scheduled for a given commit, and to limit status displays to only one project.

2.5.4.5. Repository

This attribute specifies the repository in which this change occurred. In the case of DVCS’s, this information may be required to check out the committed source code. However, using the repository from a change has security risks: if Buildbot is configured to blindly trust this information, then it may easily be tricked into building arbitrary source code, potentially compromising the workers and the integrity of subsequent builds.

2.5.4.6. Codebase

This attribute specifies the codebase to which this change was made. As described in source stamps section, multiple repositories may contain the same codebase. A change’s codebase is usually determined by the codebaseGenerator configuration. By default the codebase is ‘’; this value is used automatically for single-codebase configurations.

2.5.4.7. Revision

Each Change can have a revision attribute, which describes how to get a tree with a specific state: a tree which includes this Change (and all that came before it) but none that come after it. If this information is unavailable, the revision attribute will be None. These revisions are provided by the ChangeSource.

Revisions are always strings.

CVS: revision is the seconds since the epoch as an integer.
SVN: revision is the revision number
Darcs: revision is a large string, the output of darcs changes --context
Mercurial: revision is a short string (a hash ID), the output of hg identify
P4: revision is the transaction number
Git: revision is a short string (a SHA1 hash), the output of e.g. git rev-parse

2.5.4.8. Branches

The Change might also have a branch attribute. This indicates that all of the Change’s files are in the same named branch. The schedulers get to decide whether the branch should be built or not.

For VC systems like CVS, Git, Mercurial and Monotone the branch name is unrelated to the filename. (That is, the branch name and the filename inhabit unrelated namespaces.) For SVN, branches are expressed as subdirectories of the repository, so the file’s repourl is a combination of some base URL, the branch name, and the filename within the branch. (In a sense, the branch name and the filename inhabit the same namespace.) Darcs branches are subdirectories of a base URL just like SVN.

CVS: branch=’warner-newfeature’, files=[‘src/foo.c’]
SVN: branch=’branches/warner-newfeature’, files=[‘src/foo.c’]
Darcs: branch=’warner-newfeature’, files=[‘src/foo.c’]
Mercurial: branch=’warner-newfeature’, files=[‘src/foo.c’]
Git: branch=’warner-newfeature’, files=[‘src/foo.c’]
Monotone: branch=’warner-newfeature’, files=[‘src/foo.c’]

2.5.4.9. Change Properties

A Change may have one or more properties attached to it, usually specified through the Force Build form or sendchange. Properties are discussed in detail in the Build Properties section.

2.5.5. Schedulers

Schedulers are responsible for initiating builds on builders.

Some schedulers listen for changes from ChangeSources and generate build sets in response to these changes. Others generate build sets without changes, based on other events in the buildmaster.

2.5.5.1. Configuring Schedulers 

The schedulers configuration parameter gives a list of scheduler instances, each of which causes builds to be started on a particular set of Builders. The two basic scheduler classes you are likely to start with are SingleBranchScheduler and Periodic, but you can write a customized subclass to implement more complicated build scheduling.

Scheduler arguments should always be specified by name (as keyword arguments), to allow for future expansion:

sched = SingleBranchScheduler(name="quick", builderNames=['lin', 'win'])

There are several common arguments for schedulers, although not all are available with all schedulers.

name

Each Scheduler must have a unique name. This is used in status displays, and is also available in the build property scheduler.

builderNames

This is the set of builders which this scheduler should trigger, specified as a list of names (strings). This can also be an IRenderable object which will render to a list of builder names (or a list of IRenderable that will render to builder names).

Note

When builderNames is rendered, these additional Properties attributes are available:

master

A reference to the BuildMaster object that owns this scheduler. This can be used to access the data API.

sourcestamps

The list of sourcestamps that triggered the scheduler.

changes

The list of changes associated with the sourcestamps.

files

The list of modified files associated with the changes.

Any property attached to the change(s) that triggered the scheduler will be combined and available when rendering builderNames.

Here is a simple example:

from buildbot.plugins import util, schedulers

@util.renderer
def builderNames(props):
    builders = set()
    for f in props.files:
        if f.endswith('.rst'):
            builders.add('check_docs')
        if f.endswith('.c'):
            builders.add('check_code')
    return list(builders)

c['schedulers'] = [
    schedulers.AnyBranchScheduler(
        name='all',
        builderNames=builderNames,
    )
]

And a more complex one:

import fnmatch

from twisted.internet import defer

from buildbot.plugins import util, schedulers

@util.renderer
@defer.inlineCallbacks
def builderNames(props):
    # If "buildername_pattern" is defined with "buildbot sendchange",
    # check if the builder name matches it.
    pattern = props.getProperty('buildername_pattern')

    # If "builder_tags" is defined with "buildbot sendchange",
    # only schedule builders that have the specified tags.
    tags = props.getProperty('builder_tags')

    builders = []

    for b in (yield props.master.data.get(('builders',))):
        if pattern and not fnmatch.fnmatchcase(b['name'], pattern):
            continue
        if tags and not set(tags.split()).issubset(set(b['tags'])):
            continue
        builders.append(b['name'])

    return builders

c['schedulers'] = [
   schedulers.AnyBranchScheduler(
      name='matrix',
      builderNames=builderNames,
   )
]

properties (optional)

This is a dictionary specifying properties that will be transmitted to all builds started by this scheduler. The owner property may be of particular interest, as its contents (list) will be added to the list of “interested users” (Doing Things With Users) for each triggered build. For example:
sched = Scheduler(...,
    properties = {
        'owner': ['zorro@example.com', 'silver@example.com']
    })

codebases (optional)

Specifies codebase definitions that are used when the scheduler processes data from more than one repository at the same time.

The codebases parameter is only used to fill in missing details about a codebase when scheduling a build. For example, when a change to codebase A occurs, a scheduler must invent a sourcestamp for codebase B. Source steps that specify codebase B as their codebase will use the invented timestamp.

The parameter does not act as a filter on incoming changes – use a change filter for that purpose.

This parameter can be specified in two forms:

as a list of strings. This is the simplest form; use it if no special overrides are needed. In this form, just the names of the codebases are listed.

as a dictionary of dictionaries. In this form, the per-codebase overrides of repository, branch and revision can be specified.

Each codebase definition dictionary is a dictionary with any of the keys: repository, branch, revision. The codebase definitions are combined in a dictionary keyed by the name of the codebase.
codebases = {'codebase1': {'repository':'....',
                           'branch':'default',
                           'revision': None},
             'codebase2': {'repository':'....'} }

fileIsImportant (optional)

A callable which takes as argument a Change instance and returns True if the change is worth building, and False if it is not. Unimportant Changes are accumulated until the build is triggered by an important change. The default value of None means that all Changes are important.

change_filter (optional)

The change filter that will determine which changes are recognized by this scheduler (see ChangeFilter). Note that this is different from fileIsImportant; if the change filter filters out a change, the change is completely ignored by the scheduler. If a change is allowed by the change filter but is deemed unimportant, it will not cause builds to start but will be remembered and shown in status displays. The default value of None does not filter any changes at all.

onlyImportant (optional)

A boolean that, when True, only adds important changes to the buildset as specified in the fileIsImportant callable. This means that unimportant changes are ignored the same way a change_filter filters changes. The default value is False and only applies when fileIsImportant is given.

reason (optional)

A string that will be used as the reason for the triggered build. By default it lists the type and name of the scheduler triggering the build.

priority (optional)

Specifies the default priority for BuildRequests created by this scheduler. It can either be an integer or a function (see Scheduler Priority Functions). By default it creates BuildRequests with priority 0.

The remaining subsections represent a catalog of the available scheduler types. All these schedulers are defined in modules under buildbot.schedulers, and their docstrings are the best source of documentation on the arguments each one takes.

2.5.5.2. Scheduler Resiliency 

In a multi-master configuration, schedulers with the same name can be configured on multiple masters. Only one instance of the scheduler will be active. If that instance becomes inactive, due to its master being shut down or failing, then another instance will become active after a short delay. This provides resiliency in scheduler configurations, so that schedulers are not a single point of failure in a Buildbot infrastructure.

The Data API and web UI display the master on which each scheduler is running.

There is currently no mechanism to control which master’s scheduler instance becomes active. The behavior is nondeterministic, based on the timing of polling by inactive schedulers. The failover is non-revertive.

2.5.5.3. Usage example 

A quick scheduler might exist to give immediate feedback to developers, hoping to catch obvious problems in the code that can be detected quickly. These typically do not run the full test suite, nor do they run on a wide variety of platforms. They also usually do a VC update rather than performing a brand-new checkout each time.

A separate full scheduler might run more comprehensive tests, to catch more subtle problems. It might be configured to run after the quick scheduler, to give developers time to commit fixes to bugs caught by the quick scheduler before running the comprehensive tests. This scheduler would also feed multiple Builders.

Many schedulers can be configured to wait a while after seeing a source-code change - this is the tree stable timer. The timer allows multiple commits to be “batched” together. This is particularly useful in distributed version control systems, where a developer may push a long sequence of changes all at once. To save resources, it’s often desirable only to test the most recent change.

Schedulers can also filter out the changes they are interested in, based on a number of criteria. For example, a scheduler that only builds documentation might skip any changes that do not affect the documentation. Schedulers can also filter on the branch to which a commit was made.

Periodic builds (those which are run every N seconds rather than after new Changes arrive) are triggered by a special Periodic scheduler.

Each scheduler creates and submits BuildSet objects to the BuildMaster, which is then responsible for making sure the individual BuildRequests are delivered to the target Builders.

Scheduler instances are activated by placing them in the schedulers list in the buildmaster config file. Each scheduler must have a unique name.

2.5.5.4. Scheduler Types 

SingleBranchScheduler 

This is the original and still most popular scheduler class. It follows exactly one branch, and starts a configurable tree-stable-timer after each change on that branch. When the timer expires, it starts a build on some set of Builders. This scheduler accepts a fileIsImportant function which can be used to ignore some Changes if they do not affect any important files.

If treeStableTimer is not set, then this scheduler starts a build for every Change that matches its change_filter and satisfies fileIsImportant. If treeStableTimer is set, then a build is triggered for each set of Changes that arrive in intervals shorter than the configured time and match the filters.

Note

The behavior of this scheduler is undefined, if treeStableTimer is set, and changes from multiple branches, repositories or codebases are accepted by the filter.

Note

The codebases argument will filter out codebases not specified there, but won’t filter based on the branches specified there.

The arguments to this scheduler are:

name

See name scheduler argument.

builderNames

See builderNames scheduler argument.

properties (optional)

See properties scheduler argument.

codebases (optional)

See codebases scheduler argument.

fileIsImportant (optional)

See fileIsImportant scheduler argument.

change_filter (optional)

See change_filter scheduler argument.

onlyImportant (optional)

See onlyImportant scheduler argument.

reason (optional)

See reason scheduler argument.

treeStableTimer

The scheduler will wait for this many seconds before starting the build. If new changes are made during this interval, the timer will be restarted. So the build will be started after this many seconds of inactivity following the last change.

If treeStableTimer is None, then a separate build is started immediately for each Change.

categories (deprecated; use change_filter)

A list of categories of changes that this scheduler will respond to. If this is specified, then any non-matching changes are ignored.

branch (deprecated; use change_filter)

The scheduler will pay attention to this branch, ignoring Changes that occur on other branches. Setting branch equal to the special value of None means it should only pay attention to the default branch.

Note

None is a keyword, not a string, so write None and not "None".

Example:

from buildbot.plugins import schedulers, util
quick = schedulers.SingleBranchScheduler(
            name="quick",
            change_filter=util.ChangeFilter(branch='master'),
            treeStableTimer=60,
            builderNames=["quick-linux", "quick-netbsd"])
full = schedulers.SingleBranchScheduler(
            name="full",
            change_filter=util.ChangeFilter(branch='master'),
            treeStableTimer=5*60,
            builderNames=["full-linux", "full-netbsd", "full-OSX"])
c['schedulers'] = [quick, full]

In this example, the two quick builders are triggered 60 seconds after the tree has been changed. The full builders do not run quite that quickly (they wait 5 minutes), so that hopefully, if the quick builds fail due to a missing file or a simple typo, the developer can discover and fix the problem before the full builds are started. Both schedulers only pay attention to the default branch: any changes on other branches are ignored. Each scheduler triggers a different set of builders, referenced by name.

Note

The old names for this scheduler, buildbot.scheduler.Scheduler and buildbot.schedulers.basic.Scheduler, are deprecated in favor of using buildbot.plugins:

from buildbot.plugins import schedulers

However if you must use a fully qualified name, it is buildbot.schedulers.basic.SingleBranchScheduler.

AnyBranchScheduler 

This scheduler uses a tree-stable-timer like the default one, but uses a separate timer for each branch.

If treeStableTimer is not set, then this scheduler is indistinguishable from SingleBranchScheduler. If treeStableTimer is set, then a build is triggered for each set of Changes that arrive in intervals shorter than the configured time and match the filters.

The arguments to this scheduler are:

name

See name scheduler argument.

builderNames

See builderNames scheduler argument.

properties (optional)

See properties scheduler argument.

codebases (optional)

See codebases scheduler argument.

fileIsImportant (optional)

See fileIsImportant scheduler argument.

change_filter (optional)

See change_filter scheduler argument.

onlyImportant (optional)

See onlyImportant scheduler argument.

reason (optional)

See reason scheduler argument.

treeStableTimer

The scheduler will wait for this many seconds before starting a build. If new changes are made on the same branch during this interval, the timer will be restarted.

branches (deprecated; use change_filter)

Changes on branches not specified on this list will be ignored.

categories (deprecated; use change_filter)

A list of categories of changes that this scheduler will respond to. If this is specified, then any non-matching changes are ignored.

Dependent Scheduler 

It is common to wind up with one kind of build which should only be performed if the same source code was successfully handled by some other kind of build first. An example might be a packaging step: you might only want to produce .deb or RPM packages from a tree that was known to compile successfully and pass all unit tests. You could put the packaging step in the same Build as the compile and testing steps, but there might be other reasons to not do this (in particular you might have several Builders worth of compiles/tests, but only wish to do the packaging once). Another example is if you want to skip the full builds after a failing quick build of the same source code. Or, if one Build creates a product (like a compiled library) that is used by some other Builder, you’d want to make sure the consuming Build is run after the producing one.

You can use dependencies to express this relationship to Buildbot. There is a special kind of scheduler named Dependent that will watch an upstream scheduler for builds to complete successfully (on all of its Builders). Each time that happens, the same source code (i.e. the same SourceStamp) will be used to start a new set of builds, on a different set of Builders. This downstream scheduler doesn’t pay attention to Changes at all. It only pays attention to the upstream scheduler.

If the build fails on any of the Builders in the upstream set, the downstream builds will not fire. Note that, for SourceStamps generated by a Dependent scheduler, the revision is None, meaning HEAD. If any changes are committed between the time the upstream scheduler begins its build and the time the dependent scheduler begins its build, then those changes will be included in the downstream build. See the Triggerable scheduler for a more flexible dependency mechanism that can avoid this problem.

The arguments to this scheduler are:

name

See name scheduler argument.

builderNames

See builderNames scheduler argument.

properties (optional)

See properties scheduler argument.

codebases (optional)

See codebases scheduler argument.

upstream

The upstream scheduler to watch. Note that this is an instance, not the name of the scheduler.

Example:

from buildbot.plugins import schedulers
tests = schedulers.SingleBranchScheduler(name="just-tests",
                                         treeStableTimer=5*60,
                                         builderNames=["full-linux",
                                                       "full-netbsd",
                                                       "full-OSX"])
package = schedulers.Dependent(name="build-package",
                               upstream=tests, # <- no quotes!
                               builderNames=["make-tarball", "make-deb",
                                             "make-rpm"])
c['schedulers'] = [tests, package]

Periodic Scheduler 

This simple scheduler just triggers a build every N seconds.

The arguments to this scheduler are:

name

See name scheduler argument.

builderNames

See builderNames scheduler argument.

properties (optional)

See properties scheduler argument.

codebases (optional)

See codebases scheduler argument.

fileIsImportant (optional)

See fileIsImportant scheduler argument.

change_filter (optional)

See change_filter scheduler argument.

onlyImportant (optional)

See onlyImportant scheduler argument.

reason (optional)

See reason scheduler argument.

createAbsoluteSourceStamps (optional)

This option only has effect when using multiple codebases. When True, it uses the last seen revision for each codebase that does not have a change. When False (the default), codebases without changes will use the revision from the codebases argument.

onlyIfChanged (optional)

If this is True, then builds will be scheduled at the designated time only if the specified branch has seen an important change since the previous build. If there is no previous build or the previous build was made when this option was False then the build will be scheduled even if there are no new changes. By default this setting is False.

periodicBuildTimer

The time, in seconds, after which to start a build.

Example:

from buildbot.plugins import schedulers
nightly = schedulers.Periodic(name="daily",
                              builderNames=["full-solaris"],
                              periodicBuildTimer=24*60*60)
c['schedulers'] = [nightly]

The scheduler in this example just runs the full solaris build once per day. Note that this scheduler only lets you control the time between builds, not the absolute time-of-day of each Build, so this could easily wind up an evening or every afternoon scheduler depending upon when it was first activated.

Nightly Scheduler 

This is highly configurable periodic build scheduler, which triggers a build at particular times of day, week, month, or year. The configuration syntax is very similar to the well-known crontab format, in which you provide values for minute, hour, day, and month (some of which can be wildcards), and a build is triggered whenever the current time matches the given constraints. This can run a build every night, every morning, every weekend, alternate Thursdays, on your boss’s birthday, etc.

Pass some subset of minute, hour, dayOfMonth, month, and dayOfWeek; each may be a single number or a list of valid values. The builds will be triggered whenever the current time matches these values. Wildcards are represented by a ‘*’ string. All fields default to a wildcard except ‘minute’, so with no fields, this defaults to a build every hour, on the hour. The full list of parameters is:

name

See name scheduler argument.

builderNames

See builderNames scheduler argument.

properties (optional)

See properties scheduler argument.

codebases (optional)

See codebases scheduler argument.

fileIsImportant (optional)

See fileIsImportant scheduler argument.

change_filter (optional)

See change_filter scheduler argument.

onlyImportant (optional)

See onlyImportant scheduler argument.

reason (optional)

See reason scheduler argument.

createAbsoluteSourceStamps (optional)

This option only has effect when using multiple codebases. When True, it uses the last seen revision for each codebase that does not have a change. When False (the default), codebases without changes will use the revision from the codebases argument.

onlyIfChanged (optional)

If this is True, then builds will not be scheduled at the designated time unless the change filter has accepted an important change since the previous build. The default value is False.

branch (optional)

(Deprecated; use change_filter and codebases.) The branch to build when the time comes, and the branch to filter for if change_filter is not specified. Remember that a value of None here means the default branch, and will not match other branches!

minute (optional)

The minute of the hour on which to start the build. This defaults to 0, meaning an hourly build.

hour (optional)

The hour of the day on which to start the build, in 24-hour notation. This defaults to *, meaning every hour.

dayOfMonth (optional)

The day of the month to start a build. This defaults to *, meaning every day. Use L to specify last day of the month. Last day option respects leap years.

month (optional)

The month in which to start the build, with January = 1. This defaults to *, meaning every month. Month or month range / list as standard C abbreviated name jan-feb, jan,dec.

dayOfWeek (optional)

The day of the week to start a build, with Monday = 0. This defaults to *, meaning every day of the week or nth weekday of month. Like first Monday of month 1#1, last Monday of month L1, Monday + Friday mon,fri or ranges Monday to Friday mon-fri.

Forcing builds when there are no changes

Nightly scheduler supports scheduling builds even in there were no important changes and onlyIfChanged was set to True. This is controlled by force_at_* parameters. The feature is enabled if least one of them is set.

The time interval identified by force_at_minute, force_at_hour, force_at_day_of_month, force_at_month and force_at_day_of_week must be subset of time interval identified by minute, hour, dayOfMonth, month, dayOfWeek.

force_at_minute (optional)

The minute of the hour on which to start the build even if there were no important changes and onlyIfChanged was set to True. The default is None meaning this feature is disabled. If the feature is enabled by setting another force_at_* parameter, then the default value is 0 meaning builds will run every hour.

force_at_hour (optional)

The hour of the day on which to start the build even if there were no important changes and onlyIfChanged was set to True. The default is None meaning this feature is disabled. If the feature is enabled by setting another force_at_* parameter, then the default value is * meaning builds will run each hour.

force_at_day_of_month (optional)

The day of the month on which to start the build even if there were no important changes and onlyIfChanged was set to True. The default is None meaning this feature is disabled. If the feature is enabled by setting another force_at_* parameter, then the default value is * meaning builds will run each day.

force_at_month (optional)

The month of the year on which to start the build even if there were no important changes and onlyIfChanged was set to True. The default is None meaning this feature is disabled. If the feature is enabled by setting another force_at_* parameter, then the default value is * meaning builds will run each month.

force_at_day_of_week (optional)

The day of the week on which to start the build even if there were no important changes and onlyIfChanged was set to True. The default is None meaning this feature is disabled. If the feature is enabled by setting another force_at_* parameter, then the default value is * meaning builds will run each day of the week.

Example

For example, the following master.cfg clause will cause a build to be started every night at 3:00am:

from buildbot.plugins import schedulers, util
c['schedulers'].append(
    schedulers.Nightly(name='nightly',
                       change_filter=util.ChangeFilter(branch='master'),
                       builderNames=['builder1', 'builder2'],
                       hour=3, minute=0))

This scheduler will perform a build each Monday morning at 6:23am and again at 8:23am, but only if someone has committed code in the interim:

c['schedulers'].append(
    schedulers.Nightly(name='BeforeWork',
                       change_filter=util.ChangeFilter(branch='default'),
                       builderNames=['builder1'],
                       dayOfWeek=0, hour=[6,8], minute=23,
                       onlyIfChanged=True))

The following runs a build every two hours, using Python’s range function:

c.schedulers.append(
    schedulers.Nightly(name='every2hours',
                       change_filter=util.ChangeFilter(branch=None),  # default branch
                       builderNames=['builder1'],
                       hour=range(0, 24, 2)))

Finally, this example will run only on December 24th:

c['schedulers'].append(
    schedulers.Nightly(name='SleighPreflightCheck',
                       change_filter=util.ChangeFilter(branch=None),  # default branch
                       builderNames=['flying_circuits', 'radar'],
                       month=12,
                       dayOfMonth=24,
                       hour=12,
                       minute=0))

Try Schedulers 

This scheduler allows developers to use the buildbot try command to trigger builds of code they have not yet committed. See try for complete details.

Two implementations are available: Try_Jobdir and Try_Userpass. The former monitors a job directory, specified by the jobdir parameter, while the latter listens for PB connections on a specific port, and authenticates against userport.

The buildmaster must have a scheduler instance in the config file’s schedulers list to receive try requests. This lets the administrator control who may initiate these trial builds, which branches are eligible for trial builds, and which Builders should be used for them.

The scheduler has various means to accept build requests. All of them enforce more security than the usual buildmaster ports do. Any source code being built can be used to compromise the worker accounts, but in general that code must be checked out from the VC repository first, so only people with commit privileges can get control of the workers. The usual force-build control channels can waste worker time but do not allow arbitrary commands to be executed by people who don’t have those commit privileges. However, the source code patch that is provided with the trial build does not have to go through the VC system first, so it is important to make sure these builds cannot be abused by a non-committer to acquire as much control over the workers as a committer has. Ideally, only developers who have commit access to the VC repository would be able to start trial builds, but unfortunately, the buildmaster does not, in general, have access to the VC system’s user list.

As a result, the try scheduler requires a bit more configuration. There are currently two ways to set this up:

jobdir (ssh)

This approach creates a command queue directory, called the jobdir, in the buildmaster’s working directory. The buildmaster admin sets the ownership and permissions of this directory to only grant write access to the desired set of developers, all of whom must have accounts on the machine. The buildbot try command creates a special file containing the source stamp information and drops it in the jobdir, just like a standard maildir. When the buildmaster notices the new file, it unpacks the information inside and starts the builds.

The config file entries used by ‘buildbot try’ either specify a local queuedir (for which write and mv are used) or a remote one (using scp and ssh).

The advantage of this scheme is that it is quite secure, the disadvantage is that it requires fiddling outside the buildmaster config (to set the permissions on the jobdir correctly). If the buildmaster machine happens to also house the VC repository, then it can be fairly easy to keep the VC userlist in sync with the trial-build userlist. If they are on different machines, this will be much more of a hassle. It may also involve granting developer accounts on a machine that would not otherwise require them.

To implement this, the worker invokes ssh -l username host buildbot tryserver ARGS, passing the patch contents over stdin. The arguments must include the inlet directory and the revision information.

user+password (PB)

In this approach, each developer gets a username/password pair, which are all listed in the buildmaster’s configuration file. When the developer runs buildbot try, their machine connects to the buildmaster via PB and authenticates themselves using that username and password, then sends a PB command to start the trial build.

The advantage of this scheme is that the entire configuration is performed inside the buildmaster’s config file. The disadvantages are that it is less secure (while the cred authentication system does not expose the password in plaintext over the wire, it does not offer most of the other security properties that SSH does). In addition, the buildmaster admin is responsible for maintaining the username/password list, adding and deleting entries as developers come and go.

For example, to set up the jobdir style of trial build, using a command queue directory of MASTERDIR/jobdir (and assuming that all your project developers were members of the developers unix group), you would first set up that directory:

mkdir -p MASTERDIR/jobdir MASTERDIR/jobdir/new MASTERDIR/jobdir/cur MASTERDIR/jobdir/tmp
chgrp developers MASTERDIR/jobdir MASTERDIR/jobdir/*
chmod g+rwx,o-rwx MASTERDIR/jobdir MASTERDIR/jobdir/*

and then use the following scheduler in the buildmaster’s config file:

from buildbot.plugins import schedulers
s = schedulers.Try_Jobdir(name="try1",
                          builderNames=["full-linux", "full-netbsd", "full-OSX"],
                          jobdir="jobdir")
c['schedulers'] = [s]

Note that you must create the jobdir before telling the buildmaster to use this configuration, otherwise you will get an error. Also remember that the buildmaster must be able to read and write to the jobdir as well. Be sure to watch the twistd.log file (Logfiles) as you start using the jobdir, to make sure the buildmaster is happy with it.

Note

Patches in the jobdir are encoded using netstrings, which place an arbitrary upper limit on patch size of 99999 bytes. If your submitted try jobs are rejected with BadJobfile, try increasing this limit with a snippet like this in your master.cfg:

from twisted.protocols.basic import NetstringReceiver
NetstringReceiver.MAX_LENGTH = 1000000

To use the username/password form of authentication, create a Try_Userpass instance instead. It takes the same builderNames argument as the Try_Jobdir form, but accepts an additional port argument (to specify the TCP port to listen on) and a userpass list of username/password pairs to accept. Remember to use good passwords for this: the security of the worker accounts depends upon it:

from buildbot.plugins import schedulers
s = schedulers.Try_Userpass(name="try2",
                            builderNames=["full-linux", "full-netbsd", "full-OSX"],
                            port=8031,
                            userpass=[("alice","pw1"), ("bob", "pw2")])
c['schedulers'] = [s]

Like in most classes in Buildbot, the port argument takes a strports specification. See twisted.application.strports for details.

Triggerable Scheduler 

The Triggerable scheduler waits to be triggered by a Trigger step (see Trigger) in another build. That step can optionally wait for the scheduler’s builds to complete. This provides two advantages over Dependent schedulers. First, the same scheduler can be triggered from multiple builds. Second, the ability to wait for Triggerable’s builds to complete provides a form of “subroutine call”, where one or more builds can “call” a scheduler to perform some work for them, perhaps on other workers. The Triggerable scheduler supports multiple codebases. The scheduler filters out all codebases from Trigger steps that are not configured in the scheduler.

The parameters are just the basics:

name

See name scheduler argument.

builderNames

See builderNames scheduler argument.

properties (optional)

See properties scheduler argument.

codebases (optional)

See codebases scheduler argument.

reason (optional)

See reason scheduler argument.

This class is only useful in conjunction with the Trigger step. Here is a fully-worked example:

from buildbot.plugins import schedulers, steps, util

checkin = schedulers.SingleBranchScheduler(name="checkin",
                                           change_filter=util.ChangeFilter(branch=None),
                                           treeStableTimer=5*60,
                                           builderNames=["checkin"])
nightly = schedulers.Nightly(name='nightly',
                             change_filter=util.ChangeFilter(branch=None),
                             builderNames=['nightly'],
                             hour=3, minute=0)

mktarball = schedulers.Triggerable(name="mktarball", builderNames=["mktarball"])
build = schedulers.Triggerable(name="build-all-platforms",
                               builderNames=["build-all-platforms"])
test = schedulers.Triggerable(name="distributed-test",
                              builderNames=["distributed-test"])
package = schedulers.Triggerable(name="package-all-platforms",
                                 builderNames=["package-all-platforms"])
c['schedulers'] = [mktarball, checkin, nightly, build, test, package]

# on checkin, make a tarball, build it, and test it
checkin_factory = util.BuildFactory()
checkin_factory.addStep(steps.Trigger(schedulerNames=['mktarball'],
                                      waitForFinish=True))
checkin_factory.addStep(steps.Trigger(schedulerNames=['build-all-platforms'],
                                      waitForFinish=True))
checkin_factory.addStep(steps.Trigger(schedulerNames=['distributed-test'],
                                      waitForFinish=True))

# and every night, make a tarball, build it, and package it
nightly_factory = util.BuildFactory()
nightly_factory.addStep(steps.Trigger(schedulerNames=['mktarball'],
                                      waitForFinish=True))
nightly_factory.addStep(steps.Trigger(schedulerNames=['build-all-platforms'],
                                      waitForFinish=True))
nightly_factory.addStep(steps.Trigger(schedulerNames=['package-all-platforms'],
                                      waitForFinish=True))

NightlyTriggerable Scheduler 

class buildbot.schedulers.timed.NightlyTriggerable

The NightlyTriggerable scheduler is a mix of the Nightly and Triggerable schedulers. This scheduler triggers builds at a particular time of day, week, or year, exactly as the Nightly scheduler. However, the source stamp set that is used is provided by the last Trigger step that targeted this scheduler.

The following parameters are just the basics:

name

See name scheduler argument.

builderNames

See builderNames scheduler argument.

properties (optional)

See properties scheduler argument.

codebases (optional)

See codebases scheduler argument.

reason (optional)

See reason scheduler argument.

minute (optional)

See Nightly.

hour (optional)

See Nightly.

dayOfMonth (optional)

See Nightly.

month (optional)

See Nightly.

dayOfWeek (optional)

See Nightly.

This class is only useful in conjunction with the Trigger step. Note that waitForFinish is ignored by Trigger steps targeting this scheduler.

Here is a fully-worked example:

from buildbot.plugins import schedulers, steps, util

checkin = schedulers.SingleBranchScheduler(name="checkin",
                                           change_filter=util.ChangeFilter(branch=None),
                                           treeStableTimer=5*60,
                                           builderNames=["checkin"])
nightly = schedulers.NightlyTriggerable(name='nightly',
                                        builderNames=['nightly'],
                                        hour=3, minute=0)
c['schedulers'] = [checkin, nightly]

# on checkin, run tests
checkin_factory = util.BuildFactory([
    steps.Test(),
    steps.Trigger(schedulerNames=['nightly'])
])

# and every night, package the latest successful build
nightly_factory = util.BuildFactory([
    steps.ShellCommand(command=['make', 'package'])
])

ForceScheduler Scheduler 

The ForceScheduler scheduler is the way you can configure a force build form in the web UI.

In the /#/builders/:builderid web page, you will see, on the top right of the page, one button for each ForceScheduler scheduler that was configured for this builder. If you click on that button, a dialog will let you choose various parameters for requesting a new build.

The Buildbot framework allows you to customize exactly how the build form looks, which builders have a force build form (it might not make sense to force build every builder), and who is allowed to force builds on which builders.

You do so by configuring a ForceScheduler and adding it to the list of schedulers.

The scheduler takes the following parameters:

name

See name scheduler argument. Force buttons are ordered by this property in the UI (so you can prefix by 01, 02, etc, in order to control precisely the order).

builderNames

List of builders where the force button should appear. See builderNames scheduler argument.

reason

A parameter allowing the user to specify the reason for the build. The default value is a string parameter with a default value “force build”.

reasonString

A string that will be used to create the build reason for the forced build. This string can contain the placeholders %(owner)s and %(reason)s, which represents the value typed into the reason field.

username

A parameter specifying the username associated with the build (aka owner). The default value is a username parameter.

codebases

A list of strings or CodebaseParameter specifying the codebases that should be presented. The default is a single codebase with no name (i.e. codebases=[‘’]).

properties

A list of parameters, one for each property. These can be arbitrary parameters, where the parameter’s name is taken as the property name, or AnyPropertyParameter, which allows the web user to specify the property name. The default value is an empty list.

buttonName

The name of the “submit” button on the resulting force-build form. This defaults to the name of scheduler.

An example may be better than long explanation. What you need in your config file is something like:

from buildbot.plugins import schedulers, util

sch = schedulers.ForceScheduler(
    name="force",
    buttonName="pushMe!",
    label="My nice Force form",
    builderNames=["my-builder"],

    codebases=[
        util.CodebaseParameter(
            "",
            label="Main repository",
            # will generate a combo box
            branch=util.ChoiceStringParameter(
                name="branch",
                choices=["master", "hest"],
                default="master"),

            # will generate nothing in the form, but revision, repository,
            # and project are needed by buildbot scheduling system so we
            # need to pass a value ("")
            revision=util.FixedParameter(name="revision", default=""),
            repository=util.FixedParameter(name="repository", default=""),
            project=util.FixedParameter(name="project", default=""),
        ),
    ],

    # will generate a text input
    reason=util.StringParameter(name="reason",
                                label="reason:",
                                required=True, size=80),

    # in case you don't require authentication, this will display
    # input for user to type their name
    username=util.UserNameParameter(label="your name:",
                                    size=80),
    # A completely customized property list.  The name of the
    # property is the name of the parameter
    properties=[
        util.NestedParameter(name="options", label="Build Options",
                             layout="vertical", fields=[
            util.StringParameter(name="pull_url",
                                 label="optionally give a public Git pull url:",
                                 default="", size=80),
            util.BooleanParameter(name="force_build_clean",
                                  label="force a make clean",
                                  default=False)
        ])
    ])

This will result in the following UI:

Authorization

The force scheduler uses the web interface’s authorization framework to determine which user has the right to force which build. Here is an example of code on how you can define which user has which right:

user_mapping = {
    re.compile("project1-builder"): ["project1-maintainer", "john"] ,
    re.compile("project2-builder"): ["project2-maintainer", "jack"],
    re.compile(".*"): ["root"]
}
def force_auth(user,  status):
    global user_mapping
    for r,users in user_mapping.items():
        if r.match(status.name):
            if user in users:
                    return True
    return False

# use authz_cfg in your WebStatus setup
authz_cfg=authz.Authz(
    auth=my_auth,
    forceBuild = force_auth,
)

ForceScheduler Parameters

Most of the arguments to ForceScheduler are “parameters”. Several classes of parameters are available, each describing a different kind of input from a force-build form.

All parameter types have a few common arguments:

name (required)

The name of the parameter. For properties, this will correspond to the name of the property that your parameter will set. The name is also used internally as the identifier for in the HTML form.

label (optional; default is same as name)

The label of the parameter. This is what is displayed to the user.

tablabel (optional; default is same as label)

The label of the tab if this parameter is included into a tab layout NestedParameter. This is what is displayed to the user.

default (optional; default: “”)

The default value for the parameter that is used if there is no user input.

required (optional; default: False)

If this is true, then an error will be shown to user if there is no input in this field

maxsize (optional; default: None)

The maximum size of a field (in bytes). Buildbot will ensure the field sent by the user is not too large.

autopopulate (optional; default: None)

If not None, autopopulate is a dictionary which describes how other parameters are updated if this one changes. This is useful for when you have lots of parameters, and defaults depends on e.g. the branch. This is implemented generically, and all parameters can update others. Beware of infinite loops!

c['schedulers'].append(schedulers.ForceScheduler(
name="custom",
builderNames=["runtests"],
buttonName="Start Custom Build",
codebases = [util.CodebaseParameter(
    codebase='', project=None,
    branch=util.ChoiceStringParameter(
        name="branch",
        label="Branch",
        strict=False,
        choices=["master", "dev"],
        autopopulate={
        'master': {
            'build_name': 'build for master branch',
        },
        'dev': {
            'build_name': 'build for dev branch',
        }
        }
))],
properties=[
    util.StringParameter(
        name="build_name",
        label="Name of the Build release.",
        default="")]))  # this parameter will be auto populated when user chooses branch

The parameter types are:

NestedParameter

NestedParameter(name="options", label="Build options", layout="vertical", fields=[...]),

This parameter type is a special parameter which contains other parameters. This can be used to group a set of parameters together, and define the layout of your form. You can recursively include NestedParameter into NestedParameter, to build very complex UIs.

It adds the following arguments:

layout (optional, default is “vertical”)

The layout defines how the fields are placed in the form.

The layouts implemented in the standard web application are:

simple: fields are displayed one by one without alignment.

They take the horizontal space that they need.

vertical: all fields are displayed vertically, aligned in columns (as per the column attribute of the NestedParameter)

tabs: each field gets its own tab.

This can be used to declare complex build forms which won’t fit into one screen. The children fields are usually other NestedParameters with vertical layout.

columns (optional, accepted values are 1, 2, 3, 4)

The number of columns to use for a vertical layout. If omitted, it is set to 1 unless there are more than 3 visible child fields in which case it is set to 2.

FixedParameter

FixedParameter(name="branch", default="trunk"),

This parameter type will not be shown on the web form and always generates a property with its default value.

StringParameter

StringParameter(name="pull_url",
    label="optionally give a public Git pull url:",
    default="", size=80)

This parameter type will show a single-line text-entry box, and allow the user to enter an arbitrary string. It adds the following arguments:

regex (optional)

A string that will be compiled as a regex and used to validate the input of this parameter.

size (optional; default is 10)

The width of the input field (in characters).

TextParameter

TextParameter(name="comments",
    label="comments to be displayed to the user of the built binary",
    default="This is a development build", cols=60, rows=5)

This parameter type is similar to StringParameter, except that it is represented in the HTML form as a textarea, allowing multi-line input. It adds the StringParameter arguments and the following ones:

cols (optional; default is 80)

The number of columns the textarea will have.

rows (optional; default is 20)

The number of rows the textarea will have.

This class could be subclassed to have more customization, e.g.

developer could send a list of Git branches to pull from
developer could send a list of Gerrit changes to cherry-pick,
developer could send a shell script to amend the build.

Beware of security issues anyway.

IntParameter

IntParameter(name="debug_level",
    label="debug level (1-10)", default=2)

This parameter type accepts an integer value using a text-entry box.

BooleanParameter

BooleanParameter(name="force_build_clean",
    label="force a make clean", default=False)

This type represents a boolean value. It will be presented as a checkbox.

UserNameParameter

UserNameParameter(label="your name:", size=80)

This parameter type accepts a username. If authentication is active, it will use the authenticated user instead of displaying a text-entry box.

size (optional; default is 10)

The width of the input field (in characters).

need_email (optional; default is True)

If true, requires a full email address rather than arbitrary text.

ChoiceStringParameter

ChoiceStringParameter(name="branch",
    choices=["main","devel"], default="main")

This parameter type lets the user choose between several choices (e.g. the list of branches you are supporting, or the test campaign to run). If multiple is false, then its result is a string with one of the choices. If multiple is true, then the result is a list of strings from the choices.

Note that for some use cases, the choices need to be generated dynamically. This can be done via subclassing and overriding the ‘getChoices’ member function. An example of this is provided by the source for the InheritBuildParameter class.

Its arguments, in addition to the common options, are:

choices

The list of available choices.

strict (optional; default is True)

If true, verify that the user’s input is from the list. Note that this only affects the validation of the form request; even if this argument is False, there is no HTML form component available to enter an arbitrary value.

multiple

If true, then the user may select multiple choices.

Example:

ChoiceStringParameter(name="forced_tests",
                      label="smoke test campaign to run",
                      default=default_tests,
                      multiple=True,
                      strict=True,
                      choices=["test_builder1", "test_builder2",
                               "test_builder3"])

# .. and later base the schedulers to trigger off this property:

# triggers the tests depending on the property forced_test
builder1.factory.addStep(Trigger(name="Trigger tests",
                                schedulerNames=Property("forced_tests")))

Example of scheduler allowing to choose which worker to run on:

worker_list = ["worker1", "worker2", "worker3"]
ChoiceStringParameter(name="worker",
                      label="worker to run the build on",
                      default="*",
                      multiple=False,
                      strict=True,
                      choices=worker_list)

# .. and in nextWorker, use this property:
def nextWorker(bldr, workers, buildrequest):
    forced_worker = buildrequest.properties.getProperty("worker", "*")
    if forced_worker == "*":
        return random.choice(workers) if workers else None
    for w in workers:
        if w.worker.workername == forced_worker:
            return w
    return None  # worker not yet available

c['builders'] = [
  BuilderConfig(name='mybuild', factory=f, nextWorker=nextWorker,
        workernames=worker_list),
]

CodebaseParameter

CodebaseParameter(codebase="myrepo")

This is a parameter group to specify a sourcestamp for a given codebase.

codebase

The name of the codebase.

branch (optional; default is StringParameter)

A parameter specifying the branch to build.

revision (optional; default is StringParameter)

A parameter specifying the revision to build.

repository (optional; default is StringParameter)

A parameter specifying the repository for the build.

project (optional; default is StringParameter)

A parameter specifying the project for the build.

patch (optional; default is None)

A PatchParameter specifying that the user can upload a patch for this codebase.

FileParameter

This parameter allows the user to upload a file to a build. The user can either write some text to a text area, or select a file from the browser. Note that the file is then stored inside a property, so a maxsize of 10 megabytes has been set. You can still override that maxsize if you wish.

PatchParameter

This parameter allows the user to specify a patch to be applied at the source step. The patch is stored within the sourcestamp, and associated to a codebase. That is why PatchParameter must be set inside a CodebaseParameter.

PatchParameter is actually a NestedParameter composed of following fields:

FileParameter('body'),
IntParameter('level', default=1),
StringParameter('author', default=""),
StringParameter('comment', default=""),
StringParameter('subdir', default=".")

You can customize any of these fields by overwriting their field name e.g:

c['schedulers'] = [
    schedulers.ForceScheduler(
        name="force",
        codebases=[util.CodebaseParameter("foo", patch=util.PatchParameter(
            body=FileParameter('body', maxsize=10000)))],  # override the maximum size
                                                           # of a patch to 10k instead of 10M
        builderNames=["testy"])]

InheritBuildParameter

Note

InheritBuildParameter is not yet ported to data API, and cannot be used with buildbot nine yet (bug #3521).

This is a special parameter for inheriting force build properties from another build. The user is presented with a list of compatible builds from which to choose, and all forced-build parameters from the selected build are copied into the new build. The new parameter is:

compatible_builds

A function to find compatible builds in the build history. This function is given the master instance as first argument, and the current builder name as second argument, or None when forcing all builds.

Example:

@defer.inlineCallbacks
def get_compatible_builds(master, builder):
    if builder is None: # this is the case for force_build_all
        return ["cannot generate build list here"]
    # find all successful builds in builder1 and builder2
    builds = []
    for builder in ["builder1", "builder2"]:
        # get 40 last builds for the builder
        build_dicts = yield master.data.get(('builders', builder, 'builds'),
                                            order=['-buildid'], limit=40)
        for build_dict in build_dicts:
            if build_dict['results'] != SUCCESS:
                continue
            builds.append(builder + "/" + str(build_dict['number']))
    return builds

# ...

sched = Scheduler(...,
    properties=[
        InheritBuildParameter(
            name="inherit",
            label="promote a build for merge",
            compatible_builds=get_compatible_builds,
            required = True),
            ])

WorkerChoiceParameter

Note

WorkerChoiceParameter is not yet ported to data API, and cannot be used with buildbot nine yet (bug #3521).

This parameter allows a scheduler to require that a build is assigned to the chosen worker. The choice is assigned to the workername property for the build. The enforceChosenWorker functor must be assigned to the canStartBuild parameter for the Builder.

Example:

from buildbot.plugins import util

# schedulers:
ForceScheduler(
    # ...
    properties=[
        WorkerChoiceParameter(),
    ]
)

# builders:
BuilderConfig(
    # ...
    canStartBuild=util.enforceChosenWorker,
)

AnyPropertyParameter

This parameter type can only be used in properties, and allows the user to specify both the property name and value in the web form.

This Parameter is here to reimplement old Buildbot behavior, and should be avoided. Stricter parameter names and types should be preferred.

2.5.6. Workers

The workers configuration key specifies a list of known workers. In the common case, each worker is defined by an instance of the buildbot.worker.Worker class. It represents a standard, manually started machine that will try to connect to the Buildbot master as a worker. Buildbot also supports “on-demand”, or latent, workers, which allow Buildbot to dynamically start and stop worker instances.

2.5.6.1. Defining Workers 

A Worker instance is created with a workername and a workerpassword. These are the same two values that need to be provided to the worker administrator when they create the worker.

The workername must be unique, of course. The password exists to prevent evildoers from interfering with Buildbot by inserting their own (broken) workers into the system and thus displacing the real ones. Password may be a Secret.

Workers with an unrecognized workername or a non-matching password will be rejected when they attempt to connect, and a message describing the problem will be written to the log file (see Logfiles).

A configuration for two workers would look like:

from buildbot.plugins import worker
c['workers'] = [
    worker.Worker('bot-solaris', 'solarispasswd'),
    worker.Worker('bot-bsd', 'bsdpasswd'),
]

2.5.6.2. Worker Options 

Properties

Worker objects can also be created with an optional properties argument, a dictionary specifying properties that will be available to any builds performed on this worker. For example:

c['workers'] = [
    worker.Worker('bot-solaris', 'solarispasswd',
                  properties={'os': 'solaris'}),
]

Worker properties have priority over other sources (Builder, Scheduler, etc.). You may use the defaultProperties parameter that will only be added to Build Properties if they are not already set by another source:

c['workers'] = [
    worker.Worker('fast-bot', 'fast-passwd',
                  defaultProperties={'parallel_make': 10}),
]

Worker collects and exposes /etc/os-release fields for interpolation. These can be used to determine details about the running operating system, such as distribution and version. See https://www.linux.org/docs/man5/os-release.html for details on possible fields. Each field is imported with os_ prefix and in lower case. os_id, os_id_like, os_version_id and os_version_codename are always set, but can be null.

Limiting Concurrency

The Worker constructor can also take an optional max_builds parameter to limit the number of builds that it will execute simultaneously:

c['workers'] = [
    worker.Worker('bot-linux', 'linuxpassword',
                  max_builds=2),
]

Note

In Worker For Builders concept only one build from the same builder would run on the worker.

Master-Worker TCP Keepalive

By default, the buildmaster sends a simple, non-blocking message to each worker every hour. These keepalives ensure that traffic is flowing over the underlying TCP connection, allowing the system’s network stack to detect any problems before a build is started.

The interval can be modified by specifying the interval in seconds using the keepalive_interval parameter of Worker (defaults to 3600):

c['workers'] = [
    worker.Worker('bot-linux', 'linuxpasswd',
                  keepalive_interval=3600)
]

The interval can be set to None to disable this functionality altogether.

When Workers Go Missing

Sometimes, the workers go away. One very common reason for this is when the worker process is started once (manually) and left running, but then later the machine reboots and the process is not automatically restarted.

If you’d like to have the administrator of the worker (or other people) be notified by email when the worker has been missing for too long, just add the notify_on_missing= argument to the Worker definition. This value can be a single email address, or a list of addresses:

c['workers'] = [
    worker.Worker('bot-solaris', 'solarispasswd',
                  notify_on_missing='bob@example.com')
]

By default, this will send an email when the worker has been disconnected for more than one hour. Only one email per connection-loss event will be sent. To change the timeout, use missing_timeout= and give it a number of seconds (the default is 3600).

You can have the buildmaster send an email to multiple recipients by providing a list of addresses instead of a single one:

c['workers'] = [
    worker.Worker('bot-solaris', 'solarispasswd',
                  notify_on_missing=['bob@example.com', 'alice@example.org'],
                  missing_timeout=300)  # notify after 5 minutes
]

The email sent this way will use a MailNotifier (see MailNotifier) status target, if one is configured. This provides a way for you to control the from address of the email, as well as the relayhost (aka smarthost) to use as an SMTP server. If no MailNotifier is configured on this buildmaster, the worker-missing emails will be sent using a default configuration.

Note that if you want to have a MailNotifier for worker-missing emails but not for regular build emails, just create one with builders=[], as follows:

from buildbot.plugins import status, worker
m = status.MailNotifier(fromaddr='buildbot@localhost', builders=[],
                        relayhost='smtp.example.org')
c['reporters'].append(m)

c['workers'] = [
    worker.Worker('bot-solaris', 'solarispasswd',
                  notify_on_missing='bob@example.com')
]

Workers States

There are some times when a worker misbehaves because of issues with its configuration. In those cases, you may want to pause the worker, or maybe completely shut it down.

There are three actions that you may take (in the worker’s web page Actions dialog):

Pause: If a worker is paused, it won’t accept new builds. The action of pausing a worker will not affect any ongoing build.
Graceful Shutdown: If a worker is in graceful shutdown mode, it won’t accept new builds, but will finish the current builds. When all of its build are finished, the buildbot-worker process will terminate.
Force Shutdown: If a worker is in force shutdown mode, it will terminate immediately, and the build it was currently doing will be put to retry state.

Those actions will put the worker in either of two states:

paused: the worker is paused if it is connected but doesn’t accept new builds.
graceful: the worker is graceful if it doesn’t accept new builds, and will shutdown when builds are finished.

A worker might not be able to accept a job for a period of time if buildbot detects a misbehavior. This is called the quarantine timer.

Quarantine timer is an exponential back-off mechanism for workers. This prevents a misbehaving worker from eating the build queue by quickly finishing builds in EXCEPTION state. When misbehavior is detected, the timer will pause the worker for 10 seconds, and then the time will double with each misbehavior detection until the worker finishes a build.

The first case of misbehavior is for a latent worker to not start properly. The second case of misbehavior is for a build to end with an EXCEPTION status.

Pausing and unpausing a worker will force it to leave quarantine immediately. The quarantine timeout will not be reset until the worker finishes a build.

Worker states are stored in the database, can be queried via REST API, and are visible in the UI’s workers page.

2.5.6.3. Local Workers 

For smaller setups, you may want to just run the workers on the same machine as the master. To simplify the maintenance, you may even want to run them in the same process.

This is what LocalWorker is for. Instead of configuring a worker.Worker, you have to configure a worker.LocalWorker. As the worker is running on the same process, password is not necessary. You can run as many local workers as your machine’s CPU and memory allows.

A configuration for two workers would look like:

from buildbot.plugins import worker
c['workers'] = [
    worker.LocalWorker('bot1'),
    worker.LocalWorker('bot2'),
]

In order to use local workers you need to have buildbot-worker package installed.

2.5.6.4. Latent Workers 

The standard Buildbot model has workers started manually. The previous section described how to configure the master for this approach.

Another approach is to let the Buildbot master start workers when builds are ready, on-demand. Thanks to services such as Amazon Web Services’ Elastic Compute Cloud (“AWS EC2”), this is relatively easy to set up, and can be very useful for some situations.

The workers that are started on-demand are called “latent” workers. You can find the list of Supported Latent Workers below.

Common Options

The following options are available for all latent workers.

build_wait_timeout: This option allows you to specify how long a latent worker should wait after a build for another build before it shuts down. It defaults to 10 minutes. If this is set to 0, then the worker will be shut down immediately. If it is less than 0, it will be shut down only when shutting down master.
check_instance_interval: This option controls the interval that the health checks run during worker startup. The health checks speed up the detection of irrecoverably crashed worker (e.g. due to an issue with Docker image in the case of Docker workers). Without such checks build would continue waiting for the worker to connect until missing_timeout time elapses. The value of the option defaults to 10 seconds.

Supported Latent Workers

As of time of writing, Buildbot supports the following latent workers:

Amazon Web Services Elastic Compute Cloud (“AWS EC2”)

class buildbot.worker.ec2.EC2LatentWorker

EC2 is a web service that allows you to start virtual machines in an Amazon data center. Please see their website for details, including costs. Using the AWS EC2 latent workers involves getting an EC2 account with AWS and setting up payment; customizing one or more EC2 machine images (“AMIs”) on your desired operating system(s) and publishing them (privately if needed); and configuring the buildbot master to know how to start your customized images for “substantiating” your latent workers.

This document will guide you through setup of a AWS EC2 latent worker:

Get an AWS EC2 Account 

To start off, to use the AWS EC2 latent worker, you need to get an AWS developer account and sign up for EC2. Although Amazon often changes this process, these instructions should help you get started:

Go to http://aws.amazon.com/ and click to “Sign Up Now” for an AWS account.
Once you are logged into your account, you need to sign up for EC2. Instructions for how to do this have changed over time because Amazon changes their website, so the best advice is to hunt for it. After signing up for EC2, it may say it wants you to upload an x.509 cert. You will need this to create images (see below) but it is not technically necessary for the buildbot master configuration.
You must enter a valid credit card before you will be able to use EC2. Do that under ‘Payment Method’.
Make sure you’re signed up for EC2 by going to Your Account ‣ Account Activity and verifying EC2 is listed.

Create an AMI 

Now you need to create an AMI and configure the master. You may need to run through this cycle a few times to get it working, but these instructions should get you started.

Creating an AMI is out of the scope of this document. The EC2 Getting Started Guide is a good resource for this task. Here are a few additional hints.

When an instance of the image starts, it needs to automatically start a buildbot worker that connects to your master (to create a buildbot worker, Creating a worker; to make a daemon, Launching the daemons).
You may want to make an instance of the buildbot worker, configure it as a standard worker in the master (i.e., not as a latent worker), and test and debug it that way before you turn it into an AMI and convert to a latent worker in the master.
In order to avoid extra costs in case of master failure, you should configure the worker of the AMI with maxretries option (see Worker Options) Also see example systemd unit file example

Configure the Master with an `EC2LatentWorker`

Now let’s assume you have an AMI that should work with the EC2LatentWorker. It’s now time to set up your buildbot master configuration.

You will need some information from your AWS account: the Access Key Id and the Secret Access Key. If you’ve built the AMI yourself, you probably already are familiar with these values. If you have not, and someone has given you access to an AMI, these hints may help you find the necessary values:

While logged into your AWS account, find the “Access Identifiers” link (either on the left, or via Your Account ‣ Access Identifiers.
On the page, you’ll see alphanumeric values for “Your Access Key Id:” and “Your Secret Access Key:”. Make a note of these. Later on, we’ll call the first one your identifier and the second one your secret_identifier.

When creating an EC2LatentWorker in the buildbot master configuration, the first three arguments are required. The name and password are the first two arguments, and work the same as with normal workers. The next argument specifies the type of the EC2 virtual machine (available options as of this writing include m1.small, m1.large, m1.xlarge, c1.medium, and c1.xlarge; see the EC2 documentation for descriptions of these machines).

Here is the simplest example of configuring an EC2 latent worker. It specifies all necessary remaining values explicitly in the instantiation.

from buildbot.plugins import worker
c['workers'] = [
    worker.EC2LatentWorker('bot1', 'sekrit', 'm1.large',
                           ami='ami-12345',
                           identifier='publickey',
                           secret_identifier='privatekey'
                           keypair_name='latent_buildbot_worker',
                           security_name='latent_buildbot_worker',
                           )
]

The ami argument specifies the AMI that the master should start. The identifier argument specifies the AWS Access Key Id, and the secret_identifier specifies the AWS Secret Access Key. Both the AMI and the account information can be specified in alternate ways.

Note

Whoever has your identifier and secret_identifier values can request AWS work charged to your account, so these values need to be carefully protected. Another way to specify these access keys is to put them in a separate file. Buildbot supports the standard AWS credentials file. You can then make the access privileges stricter for this separate file, and potentially let more people read your main configuration file. If your master is running in EC2, you can also use IAM roles for EC2 to delegate permissions.

keypair_name and security_name allow you to specify different names for these AWS EC2 values.

You can make an .aws directory in the home folder of the user running the buildbot master. In that directory, create a file called credentials. The format of the file should be as follows, replacing identifier and secret_identifier with the credentials obtained before.

[default]
aws_access_key_id = identifier
aws_secret_access_key = secret_identifier

If you are using IAM roles, no config file is required. Then you can instantiate the worker as follows.

from buildbot.plugins import worker
c['workers'] = [
    worker.EC2LatentWorker('bot1', 'sekrit', 'm1.large',
                           ami='ami-12345',
                           keypair_name='latent_buildbot_worker',
                           security_name='latent_buildbot_worker',
                           )
]

Previous examples used a particular AMI. If the Buildbot master will be deployed in a process-controlled environment, it may be convenient to specify the AMI more flexibly. Rather than specifying an individual AMI, specify one or two AMI filters.

In all cases, the AMI that sorts last by its location (the S3 bucket and manifest name) will be preferred.

One available filter is to specify the acceptable AMI owners, by AWS account number (the 12 digit number, usually rendered in AWS with hyphens like “1234-5678-9012”, should be entered as in integer).

from buildbot.plugins import worker
bot1 = worker.EC2LatentWorker('bot1', 'sekrit', 'm1.large',
                              valid_ami_owners=[11111111111,
                                                22222222222],
                              identifier='publickey',
                              secret_identifier='privatekey',
                              keypair_name='latent_buildbot_worker',
                              security_name='latent_buildbot_worker',
                              )

The other available filter is to provide a regular expression string that will be matched against each AMI’s location (the S3 bucket and manifest name).

from buildbot.plugins import worker
bot1 = worker.EC2LatentWorker(
        'bot1', 'sekrit', 'm1.large',
        valid_ami_location_regex=r'buildbot\-.*/image.manifest.xml',
        identifier='publickey',
        secret_identifier='privatekey',
        keypair_name='latent_buildbot_worker',
        security_name='latent_buildbot_worker',
        )

The regular expression can specify a group, which will be preferred for the sorting. Only the first group is used; subsequent groups are ignored.

from buildbot.plugins import worker
bot1 = worker.EC2LatentWorker(
    'bot1', 'sekrit', 'm1.large',
    valid_ami_location_regex=r'buildbot\-.*\-(.*)/image.manifest.xml',
    identifier='publickey',
    secret_identifier='privatekey',
    keypair_name='latent_buildbot_worker',
    security_name='latent_buildbot_worker',
    )

If the group can be cast to an integer, it will be. This allows 10 to sort after 1, for instance.

from buildbot.plugins import worker
bot1 = worker.EC2LatentWorker(
        'bot1', 'sekrit', 'm1.large',
        valid_ami_location_regex=r'buildbot\-.*\-(\d+)/image.manifest.xml',
        identifier='publickey',
        secret_identifier='privatekey',
        keypair_name='latent_buildbot_worker',
        security_name='latent_buildbot_worker',
        )

In addition to using the password as a handshake between the master and the worker, you may want to use a firewall to assert that only machines from a specific IP can connect as workers. This is possible with AWS EC2 by using the Elastic IP feature. To configure, generate a Elastic IP in AWS, and then specify it in your configuration using the elastic_ip argument.

from buildbot.plugins import worker
c['workers'] = [
    worker.EC2LatentWorker('bot1', 'sekrit', 'm1.large',
                           'ami-12345',
                           identifier='publickey',
                           secret_identifier='privatekey',
                           elastic_ip='208.77.188.166',
                           keypair_name='latent_buildbot_worker',
                           security_name='latent_buildbot_worker',
                           )
]

One other way to configure a worker is by settings AWS tags. They can for example be used to have a more restrictive security IAM policy. To get Buildbot to tag the latent worker specify the tag keys and values in your configuration using the tags argument.

from buildbot.plugins import worker
c['workers'] = [
    worker.EC2LatentWorker('bot1', 'sekrit', 'm1.large',
                           'ami-12345',
                           identifier='publickey',
                           secret_identifier='privatekey',
                           keypair_name='latent_buildbot_worker',
                           security_name='latent_buildbot_worker',
                           tags={'SomeTag': 'foo'})
]

If the worker needs access to additional AWS resources, you can also enable your workers to access them via an EC2 instance profile. To use this capability, you must first create an instance profile separately in AWS. Then specify its name on EC2LatentWorker via instance_profile_name.

from buildbot.plugins import worker
c['workers'] = [
    worker.EC2LatentWorker('bot1', 'sekrit', 'm1.large',
                           ami='ami-12345',
                           keypair_name='latent_buildbot_worker',
                           security_name='latent_buildbot_worker',
                           instance_profile_name='my_profile'
                           )
]

You may also supply your own boto3.Session object to allow for more flexible session options (ex. cross-account) To use this capability, you must first create a boto3.Session object. Then provide it to EC2LatentWorker via session argument.

import boto3
from buildbot.plugins import worker

session = boto3.session.Session()
c['workers'] = [
    worker.EC2LatentWorker('bot1', 'sekrit', 'm1.large',
                           ami='ami-12345',
                           keypair_name='latent_buildbot_worker',
                           security_name='latent_buildbot_worker',
                           session=session
                           )
]

The EC2LatentWorker supports all other configuration from the standard Worker. The missing_timeout and notify_on_missing specify how long to wait for an EC2 instance to attach before considering the attempt to have failed, and email addresses to alert, respectively. missing_timeout defaults to 20 minutes.

Volumes 

If you want to attach existing volumes to an ec2 latent worker, use the volumes attribute. This mechanism can be valuable if you want to maintain state on a conceptual worker across multiple start/terminate sequences. volumes expects a list of (volume_id, mount_point) tuples to attempt attaching when your instance has been created.

If you want to attach new ephemeral volumes, use the block_device_map attribute. This follows the AWS API syntax, essentially acting as a passthrough. The only distinction is that the volumes default to deleting on termination to avoid leaking volume resources when workers are terminated. See boto documentation for further details.

from buildbot.plugins import worker
c['workers'] = [
    worker.EC2LatentWorker('bot1', 'sekrit', 'm1.large',
                           ami='ami-12345',
                           keypair_name='latent_buildbot_worker',
                           security_name='latent_buildbot_worker',
                           block_device_map= [
                             {
                                "DeviceName": "/dev/xvdb",
                                "Ebs" : {
                                   "VolumeType": "io1",
                                   "Iops": 1000,
                                   "VolumeSize": 100
                                }
                             }
                           ]
                           )
]

VPC Support 

If you are managing workers within a VPC, your worker configuration must be modified from above. You must specify the id of the subnet where you want your worker placed. You must also specify security groups created within your VPC as opposed to classic EC2 security groups. This can be done by passing the ids of the vpc security groups. Note, when using a VPC, you can not specify classic EC2 security groups (as specified by security_name).

from buildbot.plugins import worker
c['workers'] = [
    worker.EC2LatentWorker('bot1', 'sekrit', 'm1.large',
                           ami='ami-12345',
                           keypair_name='latent_buildbot_worker',
                           subnet_id='subnet-12345',
                           security_group_ids=['sg-12345','sg-67890']
                           )
]

Spot instances 

If you would prefer to use spot instances for running your builds, you can accomplish that by passing in a True value to the spot_instance parameter to the EC2LatentWorker constructor. Additionally, you may want to specify max_spot_price and price_multiplier in order to limit your builds’ budget consumption.

from buildbot.plugins import worker
c['workers'] = [
    worker.EC2LatentWorker('bot1', 'sekrit', 'm1.large',
                           'ami-12345', region='us-west-2',
                           identifier='publickey',
                           secret_identifier='privatekey',
                           elastic_ip='208.77.188.166',
                           keypair_name='latent_buildbot_worker',
                           security_name='latent_buildbot_worker',
                           placement='b', spot_instance=True,
                           max_spot_price=0.09,
                           price_multiplier=1.15,
                           product_description='Linux/UNIX')
]

This example would attempt to create a m1.large spot instance in the us-west-2b region costing no more than $0.09/hour. The spot prices for ‘Linux/UNIX’ spot instances in that region over the last 24 hours will be averaged and multiplied by the price_multiplier parameter, then a spot request will be sent to Amazon with the above details. If the multiple exceeds the max_spot_price, the bid price will be the max_spot_price.

Either max_spot_price or price_multiplier, but not both, may be None. If price_multiplier is None, then no historical price information is retrieved; the bid price is simply the specified max_spot_price. If the max_spot_price is None, then the multiple of the historical average spot prices is used as the bid price with no limit.

Libvirt

class buildbot.worker.libvirt.LibVirtWorker

libvirt is a virtualization API for interacting with the virtualization capabilities of recent versions of Linux and other OSes. It is LGPL and comes with a stable C API, and Python bindings.

This means we now have an API which when tied to buildbot allows us to have workers that run under Xen, QEMU, KVM, LXC, OpenVZ, User Mode Linux, VirtualBox and VMWare.

The libvirt code in Buildbot was developed against libvirt 0.7.5 on Ubuntu Lucid. It is used with KVM to test Python code on VMs, but obviously isn’t limited to that. Each build is run on a new VM, images are temporary and thrown away after each build.

This document will guide you through setup of a libvirt latent worker:

Setting up libvirt 

We won’t show you how to set up libvirt as it is quite different on each platform, but there are a few things you should keep in mind.

If you are using the system libvirt (libvirt and buildbot master are on same server), your buildbot master user will need to be in the libvirtd group.
If libvirt and buildbot master are on different servers, the user connecting to libvirt over ssh will need to be in the libvirtd group. Also need to setup authorization via ssh-keys (without password prompt).
If you are using KVM, your buildbot master user will need to be in the KVM group.
You need to think carefully about your virtual network first. Will NAT be enough? What IP will my VMs need to connect to for connecting to the master?

Configuring your base image 

You need to create a base image for your builds that has everything needed to build your software. You need to configure the base image with a buildbot worker that is configured to connect to the master on boot.

Because this image may need updating a lot, we strongly suggest scripting its creation.

If you want to have multiple workers using the same base image it can be annoying to duplicate the image just to change the buildbot credentials. One option is to use libvirt’s DHCP server to allocate an identity to the worker: DHCP sets a hostname, and the worker takes its identity from that.

Doing all this is really beyond the scope of the manual, but there is a vmbuilder script and a network.xml file to create such a DHCP server in master/contrib/ (Contrib Scripts) that should get you started:

sudo apt-get install ubuntu-vm-builder
sudo contrib/libvirt/vmbuilder

Should create an ubuntu/ folder with a suitable image in it.

virsh net-define contrib/libvirt/network.xml
virsh net-start buildbot-network

Should set up a KVM compatible libvirt network for your buildbot VM’s to run on.

Configuring your Master 

Warning

There is currently a buildbot bug that fails to use the base_image if provided. This means that the worker always uses the hd_image and changes will persist between builds. See the GitHub issue for details.

If you want to add a simple on demand VM to your setup, you only need the following. We set the username to minion1, the password to sekrit. The base image is called base_image and a copy of it will be made for the duration of the VM’s life. That copy will be thrown away every time a build is complete.

from buildbot.plugins import worker, util
c['workers'] = [
    worker.LibVirtWorker('minion1', 'sekrit',
                         uri="qemu:///session",
                         hd_image='/home/buildbot/images/minion1',
                         base_image='/home/buildbot/images/base_image')
]

You can use virt-manager to define minion1 with the correct hardware. If you don’t, buildbot won’t be able to find a VM to start.

LibVirtWorker accepts the following arguments:

name: Both a buildbot username and the name of the virtual machine.
password: A password for the buildbot to login to the master with.
hd_image: The path to a libvirt disk image, normally in qcow2 format when using KVM.
base_image: If given a base image, buildbot will clone it every time it starts a VM. This means you always have a clean environment to do your build in.
uri: The URI of the connection to libvirt.
masterFQDN: (optional, defaults to socket.getfqdn()) Address of the master the worker should connect to. Use if you master machine does not have proper fqdn. This value is passed to the libvirt image via domain metadata.
xml: If a VM isn’t predefined in virt-manager, then you can instead provide XML like that used with virsh define. The VM will be created automatically when needed, and destroyed when not needed any longer.

Note

The hd_image and base_image must be on same machine with buildbot master.

Connection to master 

If xml configuration key is not provided, then Buildbot will set libvirt metadata for the domain. It will contain the following XML element: <auth username="..." password="..." master="..."/>. Here username, password and master are the name of the worker, password to use for connection and the FQDN of the master. The libvirt metadata will be placed in the XML namespace buildbot=http://buildbot.net/.

Configuring Master to use libvirt on remote server 

If you want to use libvirt on remote server configure remote libvirt server and buildbot server following way.

Define user to connect to remote machine using ssh. Configure connection of such user to remote libvirt server (see https://wiki.libvirt.org/page/SSHSetup) without password prompt.
Add user to libvirtd group on remote libvirt server sudo usermod -G libvirtd -a <user>.

Configure remote libvirt server:

Create virtual machine for buildbot and configure it.
Change virtual machine image file to new name, which will be used as temporary image and deleted after virtual machine stops. Execute command sudo virsh edit <VM name>. In xml file locate devices/disk/source and change file path to new name. The file must not be exists, it will create via hook script.
Add hook script to /etc/libvirt/hooks/qemu to recreate VM image each start:

#!/usr/bin/python

# Script /etc/libvirt/hooks/qemu
# Don't forget to execute service libvirt-bin restart
# Also see https://www.libvirt.org/hooks.html

# This script make clean VM for each start using base image

import os
import subprocess
import sys

images_path = '/var/lib/libvirt/images/'

# build-vm - VM name in virsh list --all
# vm_base_image.qcow2 - base image file name, must exist in path /var/lib/libvirt/images/
# vm_temp_image.qcow2 - temporary image. Must not exist in path /var/lib/libvirt/images/, but
# defined in VM config file
domains = {
    'build-vm' : ['vm_base_image.qcow2', 'vm_temp_image.qcow2'],
}

def delete_image_clone(vir_domain):
    if vir_domain in domains:
        domain = domains[vir_domain]
        os.remove(images_path + domain[1])

def create_image_clone(vir_domain):
    if vir_domain in domains:
        domain = domains[vir_domain]
        cmd = ['/usr/bin/qemu-img', 'create', '-b', images_path + domain[0],
               '-f', 'qcow2', '-F', 'qcow2', images_path + domain[1]]
        subprocess.call(cmd)

if __name__ == "__main__":
    vir_domain, action = sys.argv[1:3]

    if action in ["prepare"]:
        create_image_clone(vir_domain)

    if action in ["release"]:
        delete_image_clone(vir_domain)

Configure buildbot server:

On buildbot server in virtual environment install libvirt-python package: pip install libvirt-python
Create worker using remote ssh connection.

from buildbot.plugins import worker, util
c['workers'] = [
    worker.LibVirtWorker(
        'minion1', 'sekrit',
        util.Connection("qemu+ssh://<user>@<ip address or DNS name>:<port>/session"),
        '/home/buildbot/images/minion1')
]

OpenStack

class buildbot.worker.openstack.OpenStackLatentWorker

OpenStack is a series of interconnected components that facilitates managing compute, storage, and network resources in a data center. It is available under the Apache License and has a REST interface along with a Python client.

This document will guide you through setup of an OpenStack latent worker:

Install dependencies 

OpenStackLatentWorker requires python-novaclient to work, you can install it with pip install python-novaclient.

Get an Account in an OpenStack cloud 

Setting up OpenStack is outside the domain of this document. There are four account details necessary for the Buildbot master to interact with your OpenStack cloud: username, password, a tenant name, and the auth URL to use.

Create an Image 

OpenStack supports a large number of image formats. OpenStack maintains a short list of prebuilt images; if the desired image is not listed, The OpenStack Compute Administration Manual is a good resource for creating new images. You need to configure the image with a buildbot worker to connect to the master on boot.

Configure the Master with an OpenStackLatentWorker 

With the configured image in hand, it is time to configure the buildbot master to create OpenStack instances of it. You will need the aforementioned account details. These are the same details set in either environment variables or passed as options to an OpenStack client.

OpenStackLatentWorker accepts the following arguments:

name: The worker name.
password: A password for the worker to login to the master with.
flavor: A string containing the flavor name or UUID to use for the instance.
image: A string containing the image name or UUID to use for the instance.

os_username

os_password

os_tenant_name

os_user_domain

os_project_domain

os_auth_url

The OpenStack authentication needed to create and delete instances. These are the same as the environment variables with uppercase names of the arguments.

os_auth_args

Arguments passed directly to keystone. If this is specified, other authentication parameters (see above) are ignored. You can use auth_type to specify auth plugin to load. See OpenStack documentation <https://docs.openstack.org/python-keystoneclient/> for more information. Usually this should contain auth_url, username, password, project_domain_name and user_domain_name.

block_devices

A list of dictionaries. Each dictionary specifies a block device to set up during instance creation. The values support using properties from the build and will be rendered when the instance is started.

Supported keys

uuid: (required): The image, snapshot, or volume UUID.
volume_size: (optional): Size of the block device in GiB. If not specified, the minimum size in GiB to contain the source will be calculated and used.
device_name: (optional): defaults to vda. The name of the device in the instance; e.g. vda or xda.
source_type: (optional): defaults to image. The origin of the block device. Valid values are image, snapshot, or volume.
destination_type: (optional): defaults to volume. Destination of block device: volume or local.
delete_on_termination: (optional): defaults to True. Controls if the block device will be deleted when the instance terminates.
boot_index: (optional): defaults to 0. Integer used for boot order.

meta

A dictionary of string key-value pairs to pass to the instance. These will be available under the metadata key from the metadata service.

nova_args

(optional) A dict that will be appended to the arguments when creating a VM. Buildbot uses the OpenStack Nova version 2 API by default (see client_version).

client_version

(optional) A string containing the Nova client version to use. Defaults to 2. Supports using 2.X, where X is a micro-version. Use 1.1 for the previous, deprecated, version. If using 1.1, note that an older version of novaclient will be needed so it won’t switch to using 2.

region

(optional) A string specifying region where to instantiate the worker.

Here is the simplest example of configuring an OpenStack latent worker.

from buildbot.plugins import worker
c['workers'] = [
    worker.OpenStackLatentWorker('bot2', 'sekrit',
                flavor=1, image='8ac9d4a4-5e03-48b0-acde-77a0345a9ab1',
                os_username='user', os_password='password',
                os_tenant_name='tenant',
                os_auth_url='http://127.0.0.1:35357/v2.0')
]

The image argument also supports being given a callable. The callable will be passed the list of available images and must return the image to use. The invocation happens in a separate thread to prevent blocking the build master when interacting with OpenStack.

from buildbot.plugins import worker

def find_image(images):
    # Sort oldest to newest.
    def key_fn(x):
        return x.created

    candidate_images = sorted(images, key=key_fn)
    # Return the oldest candidate image.
    return candidate_images[0]

c['workers'] = [
    worker.OpenStackLatentWorker('bot2', 'sekrit',
                flavor=1, image=find_image,
                os_username='user', os_password='password',
                os_tenant_name='tenant',
                os_auth_url='http://127.0.0.1:35357/v2.0')
]

The block_devices argument is minimally manipulated to provide some defaults and passed directly to novaclient. The simplest example is an image that is converted to a volume and the instance boots from that volume. When the instance is destroyed, the volume will be terminated as well.

from buildbot.plugins import worker
c['workers'] = [
    worker.OpenStackLatentWorker('bot2', 'sekrit',
                flavor=1, image='8ac9d4a4-5e03-48b0-acde-77a0345a9ab1',
                os_username='user', os_password='password',
                os_tenant_name='tenant',
                os_auth_url='http://127.0.0.1:35357/v2.0',
                block_devices=[
                    {'uuid': '3f0b8868-67e7-4a5b-b685-2824709bd486',
                    'volume_size': 10}])
]

The nova_args can be used to specify additional arguments for the novaclient. For example network mappings, which is required if your OpenStack tenancy has more than one network, and default cannot be determined. Please refer to your OpenStack manual whether it wants net-id or net-name.

Other useful parameters are availability_zone, security_groups and config_drive. Refer to Python bindings to the OpenStack Nova API for more information. It is found on section Servers, method create.

from buildbot.plugins import worker
c['workers'] = [
    worker.OpenStackLatentWorker('bot2', 'sekrit',
                flavor=1, image='8ac9d4a4-5e03-48b0-acde-77a0345a9ab1',
                os_username='user', os_password='password',
                os_tenant_name='tenant',
                os_auth_url='http://127.0.0.1:35357/v2.0',
                nova_args={
                  'nics': [
                            {'net-id':'uid-of-network'}
                          ]})
]

OpenStackLatentWorker supports all other configuration from the standard Worker. The missing_timeout and notify_on_missing specify how long to wait for an OpenStack instance to attach before considering the attempt to have failed and email addresses to alert, respectively. missing_timeout defaults to 20 minutes.

Docker latent worker

class buildbot.worker.docker.DockerLatentWorker

class buildbot.plugins.worker.DockerLatentWorker

Docker is an open-source project that automates the deployment of applications inside software containers. The DockerLatentWorker attempts to instantiate a fresh image for each build to assure consistency of the environment between builds. Each image will be discarded once the worker finished processing the build queue (i.e. becomes idle). See build_wait_timeout to change this behavior.

This document will guide you through the setup of such workers.

Docker Installation 

An easy way to try Docker is through installation of dedicated Virtual machines. Two of them stands out:

Beside, it is always possible to install Docker next to the buildmaster. Beware that in this case, overall performance will depend on how many builds the computer where you have your buildmaster can handle as everything will happen on the same one.

Note

It is not necessary to install Docker in the same environment as your master as we will make use to the Docker API through docker-py. More in master setup.

CoreOS

CoreOS is targeted at building infrastructure and distributed systems. In order to get the latent worker working with CoreOS, it is necessary to expose the docker socket outside of the Virtual Machine. If you installed it via Vagrant, it is also necessary to uncomment the following line in your config.rb file:

$expose_docker_tcp=2375

The following command should allow you to confirm that your Docker socket is now available via the network:

docker -H tcp://127.0.0.1:2375 ps

boot2docker

boot2docker is one of the fastest ways to boot to Docker. As it is meant to be used from outside of the Virtual Machine, the socket is already exposed. Please follow the installation instructions on how to find the address of your socket.

Image Creation 

Our build master will need the name of an image to perform its builds. Each time a new build will be requested, the same base image will be used again and again, actually discarding the result of the previous build. If you need some persistent storage between builds, you can use Volumes.

Each Docker image has a single purpose. Our worker image will be running a buildbot worker.

Docker uses Dockerfiles to describe the steps necessary to build an image. The following example will build a minimal worker. This example is voluntarily simplistic, and should probably not be used in production, see next paragraph.

FROM debian:stable
RUN apt-get update && apt-get install -y \
   python-dev \
   python-pip
RUN pip install buildbot-worker
RUN groupadd -r buildbot && useradd -r -g buildbot buildbot
RUN mkdir /worker && chown buildbot:buildbot /worker
# Install your build-dependencies here ...
USER buildbot
WORKDIR /worker
RUN buildbot-worker create-worker . <master-hostname> <workername> <workerpassword>
ENTRYPOINT ["/usr/local/bin/buildbot-worker"]
CMD ["start", "--nodaemon"]

On line 11, the hostname for your master instance, as well as the worker name and password is setup. Don’t forget to replace those values with some valid ones for your project.

It is a good practice to set the ENTRYPOINT to the worker executable, and the CMD to ["start", "--nodaemon"]. This way, no parameter will be required when starting the image.

When your Dockerfile is ready, you can build your first image using the following command (replace myworkername with a relevant name for your case):

docker build -t myworkername - < Dockerfile

Reuse same image for different workers 

Previous simple example hardcodes the worker name into the dockerfile, which will not work if you want to share your docker image between workers.

You can find in buildbot source code in master/contrib/docker one example configurations:

pythonnode_worker: a worker with Python and node installed, which demonstrate how to reuse the base worker to create variations of build environments. It is based on the official buildbot/buildbot-worker image.

The master setups several environment variables before starting the workers:

BUILDMASTER: The address of the master the worker shall connect to
BUILDMASTER_PORT: The port of the master’s worker ‘pb’ protocol.
WORKERNAME: The name the worker should use to connect to master
WORKERPASS: The password the worker should use to connect to master

Master Setup 

We will rely on docker-py to connect our master with docker. Now is the time to install it in your master environment.

Before adding the worker to your master configuration, it is possible to validate the previous steps by starting the newly created image interactively. To do this, enter the following lines in a Python prompt where docker-py is installed:

>>> import docker
>>> docker_socket = 'tcp://localhost:2375'
>>> client = docker.client.DockerClient(base_url=docker_socket)
>>> worker_image = 'my_project_worker'
>>> container = client.containers.create_container(worker_image)
>>> client.containers.start(container['Id'])
>>> # Optionally examine the logs of the master
>>> client.containers.stop(container['Id'])
>>> client.containers.wait(container['Id'])
0

It is now time to add the new worker to the master configuration under workers.

The following example will add a Docker latent worker for docker running at the following address: tcp://localhost:2375, the worker name will be docker, its password: password, and the base image name will be my_project_worker:

from buildbot.plugins import worker
c['workers'] = [
    worker.DockerLatentWorker('docker', 'password',
                              docker_host='tcp://localhost:2375',
                              image='my_project_worker')
]

password: (mandatory) The worker password part of the Latent Workers API. If the password is None, then it will be automatically generated from random number, and transmitted to the container via environment variable.

In addition to the arguments available for any Latent Workers, DockerLatentWorker will accept the following extra ones:

docker_host

(renderable string, mandatory) This is the address the master will use to connect with a running Docker instance.

image

(renderable string, mandatory) This is the name of the image that will be started by the build master. It should start a worker. This option can be a renderable, like Interpolate, so that it generates from the build request properties.

command

(optional) This will override the command setup during image creation.

volumes

(a renderable list of strings, optional) Allows to share directory between containers, or between a container and the host system. Refer to Docker documentation for more information about Volumes.

Each string within the volumes array specify a volume in the following format: volumename:bindname. The volume name has to be appended with :ro if the volume should be mounted read-only.

Note

This is the same format as when specifying volumes on the command line for docker’s own -v option.

dockerfile

(renderable string, optional if image is given) This is the content of the Dockerfile that will be used to build the specified image if the image is not found by Docker. It should be a multiline string.

Note

In case image and dockerfile are given, no attempt is made to compare the image with the content of the Dockerfile parameter if the image is found.

version

(optional, default to the highest version known by docker-py) This will indicates which API version must be used to communicate with Docker.

tls

(optional) This allow to use TLS when connecting with the Docker socket. This should be a docker.tls.TLSConfig object. See docker-py’s own documentation for more details on how to initialise this object.

followStartupLogs

(optional, defaults to false) This transfers docker container’s log inside master logs during worker startup (before connection). This can be useful to debug worker startup. e.g network issues, etc.

masterFQDN

(optional, defaults to socket.getfqdn()) Address of the master the worker should connect to. Use if you master machine does not have proper fqdn. This value is passed to the docker image via environment variable BUILDMASTER

hostconfig

(renderable dictionary, optional) Extra host configuration parameters passed as a dictionary used to create HostConfig object. See docker-py’s HostConfig documentation for all the supported options.

autopull

(optional, defaults to false) Automatically pulls image if requested image is not on docker host.

alwaysPull

(optional, defaults to false) Always pulls (update) image if autopull is set to true. Also affects the base image specified by FROM …. if using a dockerfile, autopull is not needed then.

target

(renderable string, optional) Sets target build stage for multi-stage builds when using a dockerfile.

custom_context

(renderable boolean, optional): Boolean indicating that the user wants to use custom build arguments for the docker environment. Defaults to False.

encoding

(renderable string, optional): String indicating the compression format for the build context. defaults to ‘gzip’, but ‘bzip’ can be used as well.

buildargs

(renderable dictionary, optional if custom_context is True): Dictionary, passes information for the docker to build its environment. Eg. {‘DISTRO’:’ubuntu’, ‘RELEASE’:’11.11’}. Defaults to None.

hostname

(renderable string, optional) This will set container’s hostname.

Marathon latent worker

Marathon Marathon is a production-grade container orchestration platform for Mesosphere’s Data-center Operating System (DC/OS) and Apache Mesos.

Buildbot supports using Marathon to host your latent workers. It requires either txrequests or treq to be installed to allow interaction with http server. See HTTPClientService for details.

class buildbot.worker.marathon.MarathonLatentWorker

class buildbot.plugins.worker.MarathonLatentWorker

The MarathonLatentWorker attempts to instantiate a fresh image for each build to assure consistency of the environment between builds. Each image will be discarded once the worker finished processing the build queue (i.e. becomes idle). See build_wait_timeout to change this behavior.

In addition to the arguments available for any Latent Workers, MarathonLatentWorker will accept the following extra ones:

marathon_url

(mandatory) This is the URL to Marathon server. Its REST API will be used to start docker containers.

marathon_auth

(optional) This is the optional ('userid', 'password') BasicAuth credential. If txrequests is installed, this can be a requests authentication plugin.

image

(mandatory) This is the name of the image that will be started by the build master. It should start a worker. This option can be a renderable, like Interpolate, so that it generates from the build request properties. Images are by pulled from the default docker registry. MarathonLatentWorker does not support starting a worker built from a Dockerfile.

masterFQDN

If the value contains a colon (:), then BUILDMASTER and BUILDMASTER_PORT environment variables will be passed, following scheme: masterFQDN="$BUILDMASTER:$BUILDMASTER_PORT"

marathon_extra_config

(optional, defaults to {}`) Extra configuration to be passed to Marathon API. This implementation will setup the minimal configuration to run a worker (docker image, BRIDGED network) It will let the default for everything else, including memory size, volume mounting, etc. This configuration is voluntarily very raw so that it is easy to use new marathon features. This dictionary will be merged into the Buildbot generated config, and recursively override it. See Marathon API documentation to learn what to include in this config.

Kubernetes latent worker

Kubernetes is an open-source system for automating deployment, scaling, and management of containerized applications.

Buildbot supports using Kubernetes to host your latent workers.

class buildbot.worker.kubernetes.KubeLatentWorker

class buildbot.plugins.worker.KubeLatentWorker

The KubeLatentWorker attempts to instantiate a fresh container for each build to assure consistency of the environment between builds Each container will be discarded once the worker finished processing the build queue (i.e. becomes idle). See build_wait_timeout to change this behavior.

In addition to the arguments available for any Latent Workers, KubeLatentWorker will accept the following extra ones:

image

(optional, default to buildbot/buildbot-worker) Docker image. Default to the official buildbot image.

namespace

(optional) This is the name of the namespace. Default to the current namespace

kube_config

(mandatory) This is the object specifying how to connect to the kubernetes cluster. This object must be an instance of abstract class KubeConfigLoaderBase, which have 3 implementations:

KubeHardcodedConfig
KubeCtlProxyConfigLoader
KubeInClusterConfigLoader

masterFQDN

(optional, default to None) Address of the master the worker should connect to. Put the service master service name if you want to place a load-balancer between the workers and the masters. The default behaviour is to compute address IP of the master. This option works out-of-the box inside kubernetes but don’t leverage the load-balancing through service. You can pass any callable, such as KubeLatentWorker.get_fqdn that will set masterFQDN=socket.getfqdn().

For more customization, you can subclass KubeLatentWorker and override following methods. All those methods can optionally return a deferred. All those methods take props object which is a L{IProperties} allowing to get some parameters from the build properties

createEnvironment(self, props)

This method compute the environment from your properties. Don’t forget to first call super().createEnvironment(props) to get the base properties necessary to connect to the master.
getBuildContainerResources(self, props)
This method compute the pod resources part of the container spec (spec.containers[].resources). This is important to reserve some CPU and memory for your builds, and to trigger node auto-scaling if needed. You can also limit the CPU and memory for your container.

Example:
def getBuildContainerResources(self, props):
    return {
        "requests": {
            "cpu": "2500m",
            "memory": "4G",
        }
    }
get_build_container_volume_mounts(self, props)
This method computes the volumeMounts part of the container spec.

Example:
def get_build_container_volume_mounts(self, props):
    return [
        {
            "name": "mount-name",
            "mountPath": "/cache",
        }
    ]
get_volumes(self, props)
This method computes the volumes part of the pod spec.

Example:
def get_volumes(self, props):
    return [
        {
            "name": "mount-name",
            "hostPath": {
                "path": "/var/log/pods",
            }
        }
    ]
get_node_selector(self, props)
This method computes the nodeSelector part of the pod spec.

Example:
def get_node_selector(self, props):
    return {
        "my-label": "my-label-value"
    }
get_affinity(self, props)
This method computes the affinity part of the pod spec.

Example:
def get_affinity(self, props):
    return {
        "nodeAffinity": {
            "requiredDuringSchedulingIgnoredDuringExecution": {
                "nodeSelectorTerms": [
                    "matchExpressions": [
                        {
                            "key": "topology.kubernetes.io/zone",
                            "operator": "In",
                            "values": [
                                "antarctica-east1"
                            ]
                        }
                    ]
                ]
            }
        }
    }
getServicesContainers(self, props)

This method compute a list of containers spec to put alongside the worker container. This is useful for starting services around your build pod, like a database container. All containers within the same pod share the same localhost interface, so you can access the other containers TCP ports very easily.

Kubernetes config loaders

Kubernetes provides many options to connect to a cluster. It is especially more complicated as some cloud providers use specific methods to connect to their managed kubernetes. Config loaders objects can be shared between LatentWorker.

There are three options you may use to connect to your clusters.

When running both the master and slaves run on the same Kubernetes cluster, you should use the KubeInClusterConfigLoader. If not, but having a configured kubectl tool available to the build master is an option for you, you should use KubeCtlProxyConfigLoader. If neither of these options is convenient, use KubeHardcodedConfig.

class buildbot.util.kubeclientservice.KubeCtlProxyConfigLoader

class buildbot.plugins.util.KubeCtlProxyConfigLoader

`KubeCtlProxyConfigLoader`

With KubeCtlProxyConfigLoader, buildbot will user kubectl proxy to get access to the cluster. This delegates the authentication to the kubectl golang binary, and thus avoid to implement a python version for every authentication scheme that kubernetes provides. kubectl must be available in the PATH, and configured to be able to start pods. While this method is very convenient and easy, it also opens an unauthenticated http access to your cluster via localhost. You must ensure that this is properly secured, and your buildbot master machine is not on a shared multi-user server.

proxy_port: (optional defaults to 8001) HTTP port to use.
namespace: (optional defaults to "default" default namespace to use if the latent worker do not provide one already.

class buildbot.util.kubeclientservice.KubeHardcodedConfig

class buildbot.plugins.util.KubeHardcodedConfig

`KubeHardcodedConfig`

With KubeHardcodedConfig, you just configure the necessary parameters to connect to the clusters.

master_url

(mandatory) The http url of you kubernetes master. Only http and https protocols are supported

headers

(optional) Additional headers to be passed to the HTTP request

basicAuth

(optional) Basic authorization info to connect to the cluster, as a {‘user’: ‘username’, ‘password’: ‘psw’ } dict.

Unlike the headers argument, this argument supports secret providers, e.g:

basicAuth={'user': 'username', 'password': Secret('k8spassword')}

bearerToken

(optional)

A bearer token to authenticate to the cluster, as a string. Unlike the headers argument, this argument supports secret providers, e.g:

bearerToken=Secret('k8s-token')

When using the Google Kubernetes Engine (GKE), a bearer token for the default service account can be had with:

gcloud container clusters get-credentials --region [YOURREGION] YOURCLUSTER
kubectl describe sa
kubectl describe secret [SECRET_ID]

Where SECRET_ID is displayed by the describe sa command line. The default service account does not have rights on the cluster (to create/delete pods), which is required by BuildBot’s integration. You may give it this right by making it a cluster admin with

kubectl create clusterrolebinding service-account-admin \
    --clusterrole=cluster-admin \
    --serviceaccount default:default

cert

(optional) Client certificate and key to use to authenticate. This only works if txrequests is installed:

cert=('/path/to/certificate.crt', '/path/to/certificate.key')

verify

(optional) Path to server certificate authenticate the server:

verify='/path/to/kube_server_certificate.crt'

When using the Google Kubernetes Engine (GKE), this certificate is available from the admin console, on the Cluster page. Verify that it is valid (i.e. no copy/paste errors) with openssl verify PATH_TO_PEM.

namespace

(optional defaults to "default" default namespace to use if the latent worker do not provide one already.

class buildbot.util.kubeclientservice.KubeInClusterConfigLoader

class buildbot.plugins.util.KubeInClusterConfigLoader

`KubeInClusterConfigLoader`

Use KubeInClusterConfigLoader, if your Buildbot master is itself located within the kubernetes cluster. In this case, you would associated a service account to the Buildbot master pod, and KubeInClusterConfigLoader will get the credentials from that.

This config loader takes no arguments.

UpCloud

class buildbot.worker.upcloud.UpcloudLatentWorker

UpCloud is a web service that allows you to start virtual machines in cloud. Please see their website for details, including costs.

This document will guide you through setup of a UpCloud latent worker:

Get an UpCloud Account 

To start off, to use the UpCloud latent worker, you need to sign up on UpCloud.

Go to https://www.upcloud.com/ and create an account.
Once you are logged into your account, create a sub-account for buildbot to use. You need to tick the box enabling it for API usage. You should disable the box enabling web interface. You should not use your primary account for safety and security reasons.

Configure the Master with an `UpcloudLatentWorker`

Quick-start sample

from buildbot.plugins import worker
c['workers'].append(upcloud.UpcloudLatentWorker('upcloud-worker','pass',
    image='Debian GNU/Linux 9.3 (Stretch)',
    api_username="username",
    api_password="password",
    hostconfig = {
        "user_data":"""
/usr/bin/apt-get update
/usr/bin/apt-get install -y buildbot-slave
/usr/bin/buildslave create-slave --umask=022 /buildslave buildbot.example.com upcloud-01 slavepass
/usr/bin/buildslave start /buildslave
"""}))

Complete example with default values

from buildbot.plugins import worker
c['workers'].append(upcloud.UpcloudLatentWorker('upcloud-worker','pass',
    image='Debian GNU/Linux 9.3 (Stretch)',
    api_username="username",
    api_password="password",
    hostconfig = {
        "zone":"de-fra1",
        "plan":"1xCPU-1GB",
        "hostname":"hostname",
        "ssh_keys":["ssh-rsa ...."],
        "os_disk_size":10,
        "core_number":1,
        "memory_amount":512,
        "user_data":""
    }))

The image argument specifies the name of image in the image library. UUID is not currently supported.

The api_username and api_password are for the sub-account you created on UpCloud.

hostconfig can be used to set various aspects about the created host.

zone is a valid execution zone in UpCloud environment, check their API documentation <https://developers.upcloud.com/> for valid values.
plan is a valid pre-configured machine specification, or custom if you want to define your own. See their API documentation for valid values
user_data field is used to specify startup script to run on the host.
hostname specifies the hostname for the worker. Defaults to name of the worker.
ssh_keys specifies ssh key(s) to add for root account. Some images support only one SSH key. At the time of writing, only RSA keys are supported.
os_disk_size specifies size of the system disk.
core_number can be used to specify number of cores, when plan is custom.
memory_amount can be used to specify memory in megabytes, when plan is custom.
user_data can be used to specify either URL to script, or script to execute when machine is started.

Note that by default buildbot retains latent workers for 10 minutes, see build_wait_time on how to change this.

Dangers with Latent Workers

Any latent worker that interacts with a for-fee service, such as the EC2LatentWorker, brings significant risks. As already identified, the configuration will need access to account information that, if obtained by a criminal, can be used to charge services to your account. Also, bugs in the Buildbot software may lead to unnecessary charges. In particular, if the master neglects to shut down an instance for some reason, a virtual machine may be running unnecessarily, charging against your account. Manual and/or automatic (e.g. Nagios with a plugin using a library like boto) double-checking may be appropriate.

A comparatively trivial note is that currently if two instances try to attach to the same latent worker, it is likely that the system will become confused. This should not occur, unless, for instance, you configure a normal worker to connect with the authentication of a latent buildbot. If this situation does occurs, stop all attached instances and restart the master.

2.5.7. Builder Configuration

The builders configuration key is a list of objects holding the configuration of the Builders. For more information on the Builders’ function in Buildbot, see the Concepts chapter. The class definition for the builder configuration is in buildbot.config. However, there is a simpler way to use it and it looks like this:

from buildbot.plugins import util
c['builders'] = [
    util.BuilderConfig(name='quick', workernames=['bot1', 'bot2'], factory=f_quick),
    util.BuilderConfig(name='thorough', workername='bot1', factory=f_thorough),
]

BuilderConfig takes the following keyword arguments:

name: The name of the Builder, which is used in status reports.
workername workernames: These arguments specify the worker or workers that will be used by this Builder. All worker names must appear in the workers configuration parameter. Each worker can accommodate multiple builders. The workernames parameter can be a list of names, while workername can specify only one worker.
factory: This is a buildbot.process.factory.BuildFactory instance which controls how the build is performed by defining the steps in the build. Full details appear in their own section, Build Factories.

Other optional keys may be set on each BuilderConfig:

builddir

(string, optional).

Specifies the name of a subdirectory of the master’s basedir in which everything related to this builder will be stored. This holds build status information. If not set, this parameter defaults to the builder name, with some characters escaped. Each builder must have a unique build directory.

workerbuilddir

(string, optional).

Specifies the name of a subdirectory (under the worker’s configured base directory) in which everything related to this builder will be placed on the worker. This is where checkouts, compilations, and tests are run. If not set, defaults to builddir. If a worker is connected to multiple builders that share the same workerbuilddir, make sure the worker is set to run one build at a time or ensure this is fine to run multiple builds from the same directory simultaneously.

tags

(list of strings, optional).

Identifies tags for the builder. A common use for this is to add new builders to your setup (for a new module or a new worker) that do not work correctly yet and allow you to integrate them with the active builders. You can tag these new builders with a test tag, make your main status clients ignore them, and have only private status clients pick them up. As soon as they work, you can move them over to the active tag.

project

(string, optional).

If provided, the builder will be associated with the specific project.

nextWorker

(function, optional).

If provided, this is a function that controls which worker will be assigned future jobs. The function is passed three arguments, the Builder object which is assigning a new job, a list of WorkerForBuilder objects and the BuildRequest. The function should return one of the WorkerForBuilder objects, or None if none of the available workers should be used. As an example, for each worker in the list, worker.worker will be a Worker object, and worker.worker.workername is the worker’s name. The function can optionally return a Deferred, which should fire with the same results.

To control worker selection globally for all builders, use select_next_worker.

nextBuild

(function, optional).

If provided, this is a function that controls which build request will be handled next. The function is passed two arguments, the Builder object which is assigning a new job, and a list of BuildRequest objects of pending builds. The function should return one of the BuildRequest objects, or None if none of the pending builds should be started. This function can optionally return a Deferred which should fire with the same results.

canStartBuild

(boolean, optional).

If provided, this is a function that can veto whether a particular worker should be used for a given build request. The function is passed three arguments: the Builder, a Worker, and a BuildRequest. The function should return True if the combination is acceptable, or False otherwise. This function can optionally return a Deferred which should fire with the same results.

See canStartBuild Functions for a concrete example.

locks

(list of instances of buildbot.locks.WorkerLock or buildbot.locks.MasterLock, optional).

Specifies the locks that should be acquired before starting a Build from this Builder. Alternatively, this could be a renderable that returns this list depending on properties related to the build that is just about to be created. This lets you defer picking the locks to acquire until it is known which Worker a build would get assigned to. The properties available to the renderable include all properties that are set to the build before its first step excluding the properties that come from the build itself and the builddir property that comes from worker. The Locks will be released when the build is complete. Note that this is a list of actual Lock instances, not names. Also note that all Locks must have unique names. See Interlocks.

env

(dictionary of strings, optional).

A Builder may be given a dictionary of environment variables in this parameter. The variables are used in ShellCommand steps in builds created by this builder. The environment variables will override anything in the worker’s environment. Variables passed directly to a ShellCommand will override variables of the same name passed to the Builder.

For example, if you have a pool of identical workers it is often easier to manage variables like PATH from Buildbot rather than manually editing them in the workers’ environment.

f = factory.BuildFactory
f.addStep(ShellCommand(
              command=['bash', './configure']))
f.addStep(Compile())

c['builders'] = [
  BuilderConfig(name='test', factory=f,
        workernames=['worker1', 'worker2', 'worker3', 'worker4'],
        env={'PATH': '/opt/local/bin:/opt/app/bin:/usr/local/bin:/usr/bin'}),
]

Unlike most builder configuration arguments, this argument can contain renderables.

collapseRequests

(boolean, optional)

Specifies how build requests for this builder should be collapsed. See Collapsing Build Requests, below.

properties

(dictionary of strings, optional)

A builder may be given a dictionary of Build Properties specific for this builder in this parameter. Those values can be used later on like other properties. Interpolate.

defaultProperties

(dictionary of strings, optional)

Similar to the properties parameter. But defaultProperties will only be added to Build Properties if they are not already set by another source.

description

(string, optional).

A builder may be given an arbitrary description, which will show up in the web status on the builder’s page.

description_format

(string, optional)

The format of the description parameter. By default, it is None and corresponds to plain text format. Allowed values: None, markdown.

2.5.7.1. Collapsing Build Requests 

When more than one build request is available for a builder, Buildbot can “collapse” the requests into a single build. This is desirable when build requests arrive more quickly than the available workers can satisfy them, but has the drawback that separate results for each build are not available.

Requests are only candidated for a merge if both requests have exactly the same codebases.

This behavior can be controlled globally, using the collapseRequests parameter, and on a per-Builder basis, using the collapseRequests argument to the Builder configuration. If collapseRequests is given, it completely overrides the global configuration.

Possible values for both collapseRequests configurations are:

True: Requests will be collapsed if their sourcestamp are compatible (see below for definition of compatible).
False: Requests will never be collapsed.
callable(master, builder, req1, req2): Requests will be collapsed if the callable returns true. See Collapse Request Functions for detailed example.

Sourcestamps are compatible if all of the below conditions are met:

Their codebase, branch, project, and repository attributes match exactly
Neither source stamp has a patch (e.g., from a try scheduler)
Either both source stamps are associated with changes, or neither is associated with changes but they have matching revisions.

2.5.7.2. Prioritizing Builds 

The BuilderConfig parameter nextBuild can be used to prioritize build requests within a builder. Note that this is orthogonal to Prioritizing Builders, which controls the order in which builders are called on to start their builds. The details of writing such a function are in Build Priority Functions.

Such a function can be provided to the BuilderConfig as follows:

def pickNextBuild(builder, requests):
    ...
c['builders'] = [
    BuilderConfig(name='test', factory=f,
        nextBuild=pickNextBuild,
        workernames=['worker1', 'worker2', 'worker3', 'worker4']),
]

2.5.7.3. Virtual Builders 

Dynamic Trigger is a method which allows to trigger the same builder, with different parameters. This method is used by frameworks which store the build config along side the source code like Buildbot_travis. The drawback of this method is that it is difficult to extract statistics for similar builds. The standard dashboards are not working well due to the fact that all the builds are on the same builder.

In order to overcome these drawbacks, Buildbot has the concept of virtual builder. If a build has the property virtual_builder_name, it will automatically attach to that builder instead of the original builder. That created virtual builder is not attached to any master and is only used for better sorting in the UI and better statistics. The original builder and worker configuration is still used for all other build behaviors.

The virtual builder metadata is configured with the following properties:

virtual_builder_name: The name of the virtual builder.
virtual_builder_description: The description of the virtual builder.
virtual_builder_project: The project of the virtual builder.
virtual_builder_tags: The tags for the virtual builder.

You can also use virtual builders with SingleBranchScheduler. For example if you want to automatically build all branches in your project without having to manually create a new builder each time one is added:

c['schedulers'].append(schedulers.SingleBranchScheduler(
    name='myproject-epics',
    change_filter=util.ChangeFilter(branch_re='epics/.*'),
    builderNames=['myproject-epics'],
    properties={
        'virtual_builder_name': util.Interpolate("myproject-%(ss::branch)s")
    }
))

2.5.8. Projects

The projects configuration key is a list of objects holding the configuration of the Projects. For more information on the Project function in Buildbot, see the Concepts chapter.

Project takes the following keyword arguments:

name: The name of the Project. Builders are associated to the Project using this string as their project parameter.

The following arguments are optional:

slug

(string, optional) A short string that is used to refer to the project in the URLs of the Buildbot web UI.

description

(string, optional) A description of the project that appears in the Buildbot web UI.

description_format

(string, optional)

The format of the description parameter. By default, it is None and corresponds to plain text format. Allowed values: None, markdown.

2.5.8.1. Example 

The following is a demonstration of defining several Projects in the Buildbot configuration

from buildbot.plugins import util
c['projects'] = [
    util.Project(name="example",
                 description="An application to build example widgets"),
    util.Project(name="example-utils",
                 description="Utilities for the example project"),
]

2.5.9. Build Factories

Each Builder is equipped with a build factory, which defines the steps used to perform a particular type of build. This factory is created in the configuration file, and attached to a Builder through the factory element of its dictionary.

The steps used by these builds are defined in the next section, Build Steps.

Note

Build factories are used with builders, and are not added directly to the buildmaster configuration dictionary.

2.5.9.1. Defining a Build Factory 

A BuildFactory defines the steps that every build will follow. Think of it as a glorified script. For example, a build factory which consists of an SVN checkout followed by a make build would be configured as follows:

from buildbot.plugins import util, steps

f = util.BuildFactory()
f.addStep(steps.SVN(repourl="http://..", mode="incremental"))
f.addStep(steps.Compile(command=["make", "build"]))

This factory would then be attached to one builder (or several, if desired):

c['builders'].append(
    BuilderConfig(name='quick', workernames=['bot1', 'bot2'], factory=f))

It is also possible to pass a list of steps into the BuildFactory when it is created. Using addStep is usually simpler, but there are cases where it is more convenient to create the list of steps ahead of time, perhaps using some Python tricks to generate the steps.

from buildbot.plugins import steps, util

all_steps = [
    steps.CVS(cvsroot=CVSROOT, cvsmodule="project", mode="update"),
    steps.Compile(command=["make", "build"]),
]
f = util.BuildFactory(all_steps)

Finally, you can also add a sequence of steps all at once:

f.addSteps(all_steps)

Attributes

The following attributes can be set on a build factory after it is created, e.g.,

f = util.BuildFactory()
f.useProgress = False

useProgress

(defaults to True): if True, the buildmaster keeps track of how long each step takes, so it can provide estimates of how long future builds will take. If builds are not expected to take a consistent amount of time (such as incremental builds in which a random set of files are recompiled or tested each time), this should be set to False to inhibit progress-tracking.

workdir

(defaults to ‘build’): workdir given to every build step created by this factory as default. The workdir can be overridden in a build step definition.

If this attribute is set to a string, that string will be used for constructing the workdir (worker base + builder builddir + workdir). The attribute can also be a Python callable, for more complex cases, as described in Factory Workdir Functions.

2.5.9.2. Dynamic Build Factories 

In some cases you may not know what commands to run until after you checkout the source tree. For those cases, you can dynamically add steps during a build from other steps.

The Build object provides 2 functions to do this:

addStepsAfterCurrentStep(self, step_factories): This adds the steps after the step that is currently executing.
addStepsAfterLastStep(self, step_factories): This adds the steps onto the end of the build.

Both functions only accept as an argument a list of steps to add to the build.

For example, let’s say you have a script checked in into your source tree called build.sh. When this script is called with the argument --list-stages it outputs a newline separated list of stage names. This can be used to generate at runtime a step for each stage in the build. Each stage is then run in this example using ./build.sh --run-stage <stage name>.

from buildbot.plugins import util, steps
from buildbot.process import buildstep, logobserver
from twisted.internet import defer

class GenerateStagesCommand(buildstep.ShellMixin, steps.BuildStep):

    def __init__(self, **kwargs):
        kwargs = self.setupShellMixin(kwargs)
        super().__init__(**kwargs)
        self.observer = logobserver.BufferLogObserver()
        self.addLogObserver('stdio', self.observer)

    def extract_stages(self, stdout):
        stages = []
        for line in stdout.split('\n'):
            stage = str(line.strip())
            if stage:
                stages.append(stage)
        return stages

    @defer.inlineCallbacks
    def run(self):
        # run './build.sh --list-stages' to generate the list of stages
        cmd = yield self.makeRemoteShellCommand()
        yield self.runCommand(cmd)

        # if the command passes extract the list of stages
        result = cmd.results()
        if result == util.SUCCESS:
            # create a ShellCommand for each stage and add them to the build
            self.build.addStepsAfterCurrentStep([
                steps.ShellCommand(name=stage, command=["./build.sh", "--run-stage", stage])
                for stage in self.extract_stages(self.observer.getStdout())
            ])

        return result

f = util.BuildFactory()
f.addStep(steps.Git(repourl=repourl))
f.addStep(GenerateStagesCommand(
    name="Generate build stages",
    command=["./build.sh", "--list-stages"],
    haltOnFailure=True))

2.5.9.3. Predefined Build Factories 

Buildbot includes a few predefined build factories that perform common build sequences. In practice, these are rarely used, as every site has slightly different requirements, but the source for these factories may provide examples for implementation of those requirements.

GNUAutoconf

class buildbot.process.factory.GNUAutoconf

GNU Autoconf is a software portability tool, intended to make it possible to write programs in C (and other languages) which will run on a variety of UNIX-like systems. Most GNU software is built using autoconf. It is frequently used in combination with GNU automake. These tools both encourage a build process which usually looks like this:

% CONFIG_ENV=foo ./configure --with-flags
% make all
% make check
# make install

(except, of course, from Buildbot, which always skips the make install part).

The Buildbot’s buildbot.process.factory.GNUAutoconf factory is designed to build projects which use GNU autoconf and/or automake. The configuration environment variables, the configure flags, and command lines used for the compile and test are all configurable, in general the default values will be suitable.

Example:

f = util.GNUAutoconf(source=source.SVN(repourl=URL, mode="copy"),
                     flags=["--disable-nls"])

Required Arguments:

source: This argument must be a step specification tuple that provides a BuildStep to generate the source tree.

Optional Arguments:

configure: The command used to configure the tree. Defaults to ./configure. Accepts either a string or a list of shell argv elements.
configureEnv: The environment used for the initial configuration step. This accepts a dictionary which will be merged into the worker’s normal environment. This is commonly used to provide things like CFLAGS="-O2 -g" (to turn off debug symbols during the compile). Defaults to an empty dictionary.
configureFlags: A list of flags to be appended to the argument list of the configure command. This is commonly used to enable or disable specific features of the autoconf-controlled package, like ["--without-x"] to disable windowing support. Defaults to an empty list.
reconf: use autoreconf to generate the ./configure file, set to True to use a buildbot default autoreconf command, or define the command for the ShellCommand.
compile: this is a shell command or list of argv values which is used to actually compile the tree. It defaults to make all. If set to None, the compile step is skipped.
test: this is a shell command or list of argv values which is used to run the tree’s self-tests. It defaults to make check. If set to None, the test step is skipped.
distcheck: this is a shell command or list of argv values which is used to run the packaging test. It defaults to make distcheck. If set to None, the test step is skipped.

BasicBuildFactory

class buildbot.process.factory.BasicBuildFactory

This is a subclass of GNUAutoconf which assumes the source is in CVS, and uses mode='full' and method='clobber' to always build from a clean working copy.

QuickBuildFactory

class buildbot.process.factory.QuickBuildFactory

The QuickBuildFactory class is a subclass of GNUAutoconf which assumes the source is in CVS, and uses mode='incremental' to get incremental updates.

The difference between a full build and a quick build is that quick builds are generally done incrementally, starting with the tree where the previous build was performed. That simply means that the source-checkout step should be given a mode='incremental' flag, to do the source update in-place.

In addition to that, this class sets the useProgress flag to False. Incremental builds will (or at least the ought to) compile as few files as necessary, so they will take an unpredictable amount of time to run. Therefore it would be misleading to claim to predict how long the build will take.

This class is probably not of use to new projects.

BasicSVN

class buildbot.process.factory.BasicSVN

This class is similar to QuickBuildFactory, but uses SVN instead of CVS.

CPAN

class buildbot.process.factory.CPAN

Most Perl modules available from the CPAN archive use the MakeMaker module to provide configuration, build, and test services. The standard build routine for these modules looks like:

% perl Makefile.PL
% make
% make test
# make install

(except again Buildbot skips the install step)

Buildbot provides a CPAN factory to compile and test these projects.

Arguments:

source: (required): A step specification tuple, like that used by GNUAutoconf.
perl: A string which specifies the perl executable to use. Defaults to just perl.

Distutils

Deprecated since version 4.0.

class buildbot.process.factory.Distutils

Most Python modules use the distutils package to provide configuration and build services. The standard build process looks like:

% python ./setup.py build
% python ./setup.py install

Unfortunately, although Python provides a standard unit-test framework named unittest, to the best of my knowledge, distutils does not provide a standardized target to run such unit tests. (Please let me know if I’m wrong, and I will update this factory.)

The Distutils factory provides support for running the build part of this process. It accepts the same source= parameter as the other build factories.

Arguments:

source: (required): A step specification tuple, like that used by GNUAutoconf.
python: A string which specifies the python executable to use. Defaults to just python.
test: Provides a shell command which runs unit tests. This accepts either a string or a list. The default value is None, which disables the test step (since there is no common default command to run unit tests in distutils modules).

Trial

class buildbot.process.factory.Trial

Twisted provides a unit test tool named trial which provides a few improvements over Python’s built-in unittest module. Many Python projects which use Twisted for their networking or application services also use trial for their unit tests. These modules are usually built and tested with something like the following:

% python ./setup.py build
% PYTHONPATH=build/lib.linux-i686-2.3 trial -v PROJECTNAME.test
% python ./setup.py install

Unfortunately, the build/lib directory into which the built/copied .py files are placed is actually architecture-dependent, and I do not yet know of a simple way to calculate its value. For many projects it is sufficient to import their libraries in place from the tree’s base directory (PYTHONPATH=.).

In addition, the PROJECTNAME value where the test files are located is project-dependent: it is usually just the project’s top-level library directory, as common practice suggests the unit test files are put in the test sub-module. This value cannot be guessed, the Trial class must be told where to find the test files.

The Trial class provides support for building and testing projects which use distutils and trial. If the test module name is specified, trial will be invoked. The library path used for testing can also be set.

One advantage of trial is that the Buildbot happens to know how to parse trial output, letting it identify which tests passed and which ones failed. The Buildbot can then provide fine-grained reports about how many tests have failed, when individual tests fail when they had been passing previously, etc.

Another feature of trial is that you can give it a series of source .py files, and it will search them for special test-case-name tags that indicate which test cases provide coverage for that file. Trial can then run just the appropriate tests. This is useful for quick builds, where you want to only run the test cases that cover the changed functionality.

Arguments:

testpath: Provides a directory to add to PYTHONPATH when running the unit tests, if tests are being run. Defaults to . to include the project files in-place. The generated build library is frequently architecture-dependent, but may simply be build/lib for pure-Python modules.
python: Which Python executable to use. This list will form the start of the argv array that will launch trial. If you use this, you should set trial to an explicit path (like /usr/bin/trial or ./bin/trial). The parameter defaults to None, which leaves it out entirely (running trial args instead of python ./bin/trial args). Likely values are ['python'], ['python2.2'], or ['python', '-Wall'].
trial: Provides the name of the trial command. It is occasionally useful to use an alternate executable, such as trial2.2 which might run the tests under an older version of Python. Defaults to trial.
trialMode: A list of arguments to pass to trial, specifically to set the reporting mode. This defaults to ['--reporter=bwverbose'], which only works for Twisted-2.1.0 and later.
trialArgs: A list of arguments to pass to trial, available to turn on any extra flags you like. Defaults to [].
tests: Provides a module name or names which contain the unit tests for this project. Accepts a string, typically PROJECTNAME.test, or a list of strings. Defaults to None, indicating that no tests should be run. You must either set this or testChanges.
testChanges: If True, ignore the tests parameter and instead ask the Build for all the files that make up the Changes going into this build. Pass these filenames to trial and ask it to look for test-case-name tags, running just the tests necessary to cover the changes.
recurse: If True, tells Trial (with the --recurse argument) to look in all subdirectories for additional test cases.
reactor: which reactor to use, like ‘gtk’ or ‘java’. If not provided, the Twisted’s usual platform-dependent default is used.
randomly: If True, tells Trial (with the --random=0 argument) to run the test cases in random order, which sometimes catches subtle inter-test dependency bugs. Defaults to False.

The step can also take any of the ShellCommand arguments, e.g., haltOnFailure.

Unless one of tests or testChanges are set, the step will generate an exception.

2.5.10. Build Sets

A BuildSet represents a set of Builds that all compile and/or test the same version of the source tree. Usually, these builds are created by multiple Builders and will thus execute different steps.

The BuildSet is tracked as a single unit, which fails if any of the component Builds have failed, and therefore can succeed only if all of the component Builds have succeeded. There are two kinds of status notification messages that can be emitted for a BuildSet: the firstFailure type (which fires as soon as we know the BuildSet will fail), and the Finished type (which fires once the BuildSet has completely finished, regardless of whether the overall set passed or failed).

A BuildSet is created with a set of one or more source stamp tuples of (branch, revision, changes, patch), some of which may be None, and a list of Builders on which it is to be run. They are then given to the BuildMaster, which is responsible for creating a separate BuildRequest for each Builder.

There are a couple of different likely values for the SourceStamp:

(revision=None, changes=CHANGES, patch=None): This is a SourceStamp used when a series of Changes have triggered a build. The VC step will attempt to check out a tree that contains CHANGES (and any changes that occurred before CHANGES, but not any that occurred after them.)
(revision=None, changes=None, patch=None): This builds the most recent code on the default branch. This is the sort of SourceStamp that would be used on a Build that was triggered by a user request, or a Periodic scheduler. It is also possible to configure the VC Source Step to always check out the latest sources rather than paying attention to the Changes in the SourceStamp, which will result in the same behavior as this.
(branch=BRANCH, revision=None, changes=None, patch=None): This builds the most recent code on the given BRANCH. Again, this is generally triggered by a user request or a Periodic scheduler.
(revision=REV, changes=None, patch=(LEVEL, DIFF, SUBDIR_ROOT)): This checks out the tree at the given revision REV, then applies a patch (using patch -pLEVEL <DIFF) from inside the relative directory SUBDIR_ROOT. Item SUBDIR_ROOT is optional and defaults to the builder working directory. The try command creates this kind of SourceStamp. If patch is None, the patching step is bypassed.

The buildmaster is responsible for turning the BuildSet into a set of BuildRequest objects and queueing them on the appropriate Builders.

2.5.11. Properties

Build properties are a generalized way to provide configuration information to build steps; see Build Properties for the conceptual overview of properties.

Some build properties come from external sources and are set before the build begins; others are set during the build and are available for later steps. The sources for properties are:

global configuration: These properties apply to all builds.
schedulers: A scheduler can specify properties that become available to all builds it starts.
changes: A change can have properties attached to it, supplying extra information gathered by the change source. This is most commonly used with the sendchange command.
forced builds: The “Force Build” form allows users to specify properties
workers: A worker can pass properties on to the builds it performs.
builds: A build automatically sets a number of properties on itself.
builders: A builder can set properties on all the builds it runs.
steps: The steps of a build can set properties that are available to subsequent steps. In particular, source steps set the got_revision property.

If the same property is supplied in multiple places, the final appearance takes precedence. For example, a property set in a builder configuration will override the one supplied by the scheduler.

Properties are stored internally in JSON format, so they are limited to basic types of data: numbers, strings, lists, and dictionaries.

2.5.11.1. Common Build Properties 

The following build properties are set when the build is started, and are available to all steps.

got_revision

This property is set when a Source step checks out the source tree, and provides the revision that was actually obtained from the VC system. In general this should be the same as revision, except for non-absolute sourcestamps, where got_revision indicates what revision was current when the checkout was performed. This can be used to rebuild the same source code later.

Note

For some VC systems (Darcs in particular), the revision is a large string containing newlines, and is not suitable for interpolation into a filename.

For multi-codebase builds (where codebase is not the default ‘’), this property is a dictionary, keyed by codebase.

buildername: This is a string that indicates which Builder the build was a part of. The combination of buildername and buildnumber uniquely identify a build.

builderid: This is a number that indicates which Builder the build was a part of.

buildnumber: Each build gets a number, scoped to the Builder (so the first build performed on any given Builder will have a build number of 0). This integer property contains the build’s number.

workername: This is a string which identifies which worker the build is running on.

scheduler: If the build was started from a scheduler, then this property will contain the name of that scheduler.
builddir: The absolute path of the base working directory on the worker of the current builder.

For single codebase builds, where the codebase is ‘’, the following Source Stamp Attributes are also available as properties: branch, revision, repository, and project .

2.5.11.2. Source Stamp Attributes 

branch revision repository project codebase

For details of these attributes see Concepts.

changes

This attribute is a list of dictionaries representing the changes that make up this sourcestamp.

2.5.11.3. Using Properties in Steps 

For the most part, properties are used to alter the behavior of build steps during a build. This is done by using renderables (objects implementing the IRenderable interface) as step parameters. When the step is started, each such object is rendered using the current values of the build properties, and the resultant rendering is substituted as the actual value of the step parameter.

Buildbot offers several renderable object types covering common cases. It’s also possible to create custom renderables.

Note

Properties are defined while a build is in progress; their values are not available when the configuration file is parsed. This can sometimes confuse newcomers to Buildbot! In particular, the following is a common error:

if Property('release_train') == 'alpha':
    f.addStep(...)

This does not work because the value of the property is not available when the if statement is executed. However, Python will not detect this as an error - you will just never see the step added to the factory.

You can use renderables in most step parameters. Please file bugs for any parameters which do not accept renderables.

Property

The simplest renderable is Property, which renders to the value of the property named by its argument:

from buildbot.plugins import steps, util

f.addStep(steps.ShellCommand(command=['echo', 'buildername:',
                             util.Property('buildername')]))

You can specify a default value by passing a default keyword argument:

f.addStep(steps.ShellCommand(command=['echo', 'warnings:',
                             util.Property('warnings', default='none')]))

The default value is used when the property doesn’t exist, or when the value is something Python regards as False. The defaultWhenFalse argument can be set to False to force Buildbot to use the default argument only if the parameter is not set:

f.addStep(steps.ShellCommand(command=['echo', 'warnings:',
                             util.Property('warnings', default='none',
                                           defaultWhenFalse=False)]))

The default value can be a renderable itself, e.g.,

command=util.Property('command', default=util.Property('default-command'))

Interpolate

Property can only be used to replace an entire argument: in the example above, it replaces an argument to echo. Often, properties need to be interpolated into strings, instead. The tool for that job is Interpolate.

The more common pattern is to use Python dictionary-style string interpolation by using the %(prop:<propname>)s syntax. In this form, the property name goes in the parentheses, as above. A common mistake is to omit the trailing “s”, leading to a rather obscure error from Python (“ValueError: unsupported format character”).

from buildbot.plugins import steps, util
f.addStep(steps.ShellCommand(
    command=['make',
            util.Interpolate('REVISION=%(prop:got_revision)s'),
            'dist']))

This example will result in a make command with an argument like REVISION=12098.

The syntax of dictionary-style interpolation is a selector, followed by a colon, followed by a selector specific key, optionally followed by a colon and a string indicating how to interpret the value produced by the key.

The following selectors are supported.

prop: The key is the name of a property.
src: The key is a codebase and source stamp attribute, separated by a colon. Note, the syntax is %(src:<codebase>:<ssattr>)s, which differs from other selectors.
kw: The key refers to a keyword argument passed to Interpolate. Those keyword arguments may be ordinary values or renderables.
secret: The key refers to a secret provided by a provider declared in secretsProviders .
worker: The key refers to an info item provided by workers.

The following ways of interpreting the value are available.

-replacement: If the key exists, substitute its value; otherwise, substitute replacement. replacement may be empty (default), %(prop:propname:-)s.
~replacement: Like -replacement, but only substitutes the value of the key if it is something Python regards as True. Python considers None, 0, empty lists, and the empty string to be false, so such values will be replaced by replacement.
+replacement: If the key exists, substitute replacement; otherwise, substitute an empty string.

?|sub_if_exists|sub_if_missing

#?|sub_if_true|sub_if_false: Ternary substitution, depending on either the key being present (with ?, similar to +) or being True (with #?, like ~). Notice that there is a pipe immediately following the question mark and between the two substitution alternatives. The character that follows the question mark is used as the delimiter between the two alternatives. In the above examples, it is a pipe, but any character other than ( can be used.

Note

Although these are similar to shell substitutions, no other substitutions are currently supported.

Example:

from buildbot.plugins import steps, util
f.addStep(steps.ShellCommand(
    command=[
        'save-build-artifacts-script.sh',
        util.Interpolate('-r %(prop:repository)s'),
        util.Interpolate('-b %(src::branch)s'),
        util.Interpolate('-d %(kw:data)s', data="some extra needed data")
    ]))

Note

We use %(src::branch)s in most examples, because codebase is empty by default.

Example:

from buildbot.plugins import steps, util
f.addStep(steps.ShellCommand(
    command=[
        'make',
        util.Interpolate('REVISION=%(prop:got_revision:-%(src::revision:-unknown)s)s'),
        'dist'
    ]))

In addition, Interpolate supports using positional string interpolation. Here, %s is used as a placeholder, and the substitutions (which may be renderables) are given as subsequent arguments:

f.addStep(steps.ShellCommand(
    command=[
        'echo',
        util.Interpolate('%d warnings and %d errors',
                         util.Property('warnings'),
                         util.Property('errors'))
    ]))

Note

Like Python, you can use either positional interpolation or dictionary-style interpolation, but not both. Thus you cannot use a string like Interpolate("foo-%(src::revision)s-%s", "branch").

Renderer

While Interpolate can handle many simple cases, and even some common conditionals, more complex cases are best handled with Python code. The renderer decorator creates a renderable object whose rendering is obtained by calling the decorated function when the step to which it’s passed begins. The function receives an IProperties object, which it can use to examine the values of any and all properties. For example:

from buildbot.plugins import steps, util

@util.renderer
def makeCommand(props):
    command = ['make']
    cpus = props.getProperty('CPUs')
    if cpus:
        command.extend(['-j', str(cpus+1)])
    else:
        command.extend(['-j', '2'])
    command.extend([util.Interpolate('%(prop:MAKETARGET)s')])
    return command

f.addStep(steps.ShellCommand(command=makeCommand))

You can think of renderer as saying “call this function when the step starts”.

Note

Since 0.9.3, renderer can itself return IRenderable objects or containers containing IRenderable.

Optionally, extra arguments may be passed to the rendered function at any time by calling withArgs on the renderable object. The withArgs method accepts *args and **kwargs arguments which are stored in a new renderable object which is returned. The original renderable object is not modified. Multiple withArgs calls may be chained. The passed *args and **kwargs parameters are rendered and the results are passed to the rendered function at the time it is itself rendered. For example:

from buildbot.plugins import steps, util

@util.renderer
def makeCommand(props, target):
    command = ['make']
    cpus = props.getProperty('CPUs')
    if cpus:
        command.extend(['-j', str(cpus+1)])
    else:
        command.extend(['-j', '2'])
    command.extend([target])
    return command

f.addStep(steps.ShellCommand(command=makeCommand.withArgs('mytarget')))

Note

The rendering of the renderable object may happen at unexpected times, so it is best to ensure that the passed extra arguments are not changed.

Note

Config errors with Renderables may not always be caught via checkconfig.

Transform

Transform is an alternative to renderer. While renderer is useful for creating new renderables, Transform is easier to use when you want to transform or combine the renderings of preexisting renderables.

Transform takes a function and any number of positional and keyword arguments. The function must either be a callable object or a renderable producing one. When rendered, a Transform first replaces all of its arguments that are renderables with their renderings, then calls the function, passing it the positional and keyword arguments, and returns the result as its own rendering.

For example, suppose my_path is a path on the worker, and you want to get it relative to the build directory. You can do it like this:

import os.path
from buildbot.plugins import util

my_path_rel = util.Transform(os.path.relpath, my_path, start=util.Property('builddir'))

This works whether my_path is an ordinary string or a renderable. my_path_rel will be a renderable in either case, however.

FlattenList

If a nested list should be flattened for some renderables, FlattenList can be used. For example:

from buildbot.plugins import steps, util
f.addStep(steps.ShellCommand(
    command=[ 'make' ],
    descriptionDone=util.FlattenList([ 'make ', [ 'done' ]])
))

descriptionDone will be set to [ 'make', 'done' ] when the ShellCommand executes. This is useful when a list-returning property is used in renderables.

Note

ShellCommand automatically flattens nested lists in its command argument, so there is no need to use FlattenList for it.

WithProperties

Warning

This class is deprecated. It is an older version of Interpolate. It exists for compatibility with older configs.

The simplest use of this class is with positional string interpolation. Here, %s is used as a placeholder, and property names are given as subsequent arguments:

from buildbot.plugins import steps, util
f.addStep(steps.ShellCommand(
    command=["tar", "czf",
            util.WithProperties("build-%s-%s.tar.gz", "branch", "revision"),
            "source"]))

If this BuildStep were used in a tree obtained from Git, it would create a tarball with a name like build-master-a7d3a333db708e786edb34b6af646edd8d4d3ad9.tar.gz.

The more common pattern is to use Python dictionary-style string interpolation by using the %(propname)s syntax. In this form, the property name goes in the parentheses, as above. A common mistake is to omit the trailing “s”, leading to a rather obscure error from Python (“ValueError: unsupported format character”).

from buildbot.plugins import steps, util
f.addStep(steps.ShellCommand(
    command=['make',
            util.WithProperties('REVISION=%(got_revision)s'),
            'dist']))

This example will result in a make command with an argument like REVISION=12098.

The dictionary-style interpolation supports a number of more advanced syntaxes in the parentheses.

propname:-replacement: If propname exists, substitute its value; otherwise, substitute replacement. replacement may be empty (%(propname:-)s)
propname:~replacement: Like propname:-replacement, but only substitutes the value of property propname if it is something Python regards as True. Python considers None, 0, empty lists, and the empty string to be false, so such values will be replaced by replacement.
propname:+replacement: If propname exists, substitute replacement; otherwise, substitute an empty string.

Although these are similar to shell substitutions, no other substitutions are currently supported, and replacement in the above cannot contain more substitutions.

Note: like Python, you can use either positional interpolation or dictionary-style interpolation, not both. Thus you cannot use a string like WithProperties("foo-%(revision)s-%s", "branch").

Custom Renderables

If the options described above are not sufficient, more complex substitutions can be achieved by writing custom renderables.

The IRenderable interface is simple - objects must provide a getRenderingFor method. The method should take one argument - an IProperties provider - and should return the rendered value or a deferred firing with one. You can pass instances of the class anywhere other renderables are accepted. For example:

import time
from buildbot.interfaces import IRenderable
from zope.interface import implementer

@implementer(IRenderable)
class DetermineFoo(object):
    def getRenderingFor(self, props):
        if props.hasProperty('bar'):
            return props['bar']
        elif props.hasProperty('baz'):
            return props['baz']
        return 'qux'
ShellCommand(command=['echo', DetermineFoo()])

or, more practically,

from buildbot.interfaces import IRenderable
from zope.interface import implementer
from buildbot.plugins import util

@implementer(IRenderable)
class Now(object):
    def getRenderingFor(self, props):
        return time.clock()
ShellCommand(command=['make', util.Interpolate('TIME=%(kw:now)s', now=Now())])

This is equivalent to:

from buildbot.plugins import util

@util.renderer
def now(props):
    return time.clock()
ShellCommand(command=['make', util.Interpolate('TIME=%(kw:now)s', now=now)])

Note that a custom renderable must be instantiated (and its constructor can take whatever arguments you like), whereas a function decorated with renderer can be used directly.

URL for build

Its common to need to use the URL for the build in a step. For this, you can use a special custom renderer as following:

from buildbot.plugins import *

ShellCommand(command=['make', util.Interpolate('BUILDURL=%(kw:url)s', url=util.URLForBuild)])

Renderable Comparison

Its common to need to make basic comparison or calculation with properties. The Property and Interpolate objects contain necessary operator overloads to make this possible.

from buildbot.plugins import *

ShellCommand(command=['make'], doStepIf=Interpolate("worker:os_id")  == 'ubuntu')

In previous code, the value of the comparison can only be computed at runtime, so the result of the comparison is actually a renderable which will be computed at the start of the step.

from buildbot.plugins import *

ShellCommand(command=['make'], doStepIf=Interpolate("worker:os_id").in_(['debian', 'ubuntu']))

‘in’ operator cannot be overloaded, so we add a simple in_ method to Property and Interpolate.

Currently supported operators are in_, ==, !=, <, <=, >, >=, +, -, *, /, //, %.

2.5.12. Build Steps

2.5.12.1. Parameters Common to all Steps

All BuildSteps accept some common parameters. Some of these control how their individual status affects the overall build. Others are used to specify which Locks (see Interlocks) should be acquired before allowing the step to run.

Note that it is not possible to change the configuration of the BuildStep by adjusting its attributes after construction. Use set_step_arg(name, value) function for that.

Arguments common to all BuildStep subclasses:

name: The name used to describe the step on the status display. Since 0.9.8, this argument might be renderable.

haltOnFailure: If True, a FAILURE of this build step will cause the build to halt immediately. Any steps with alwaysRun=True will still be run. Generally speaking, haltOnFailure implies flunkOnFailure (the default for most BuildSteps). In some cases, particularly with a series of tests, it makes sense to haltOnFailure if something fails early on but not flunkOnFailure. This can be achieved with haltOnFailure=True, flunkOnFailure=False.

flunkOnWarnings: When True, a WARNINGS or FAILURE of this build step will mark the overall build as FAILURE. The remaining steps will still be executed.

flunkOnFailure: When True, a FAILURE of this build step will mark the overall build as a FAILURE. The remaining steps will still be executed.

warnOnWarnings: When True, a WARNINGS or FAILURE of this build step will mark the overall build as having WARNINGS. The remaining steps will still be executed.

warnOnFailure: When True, a FAILURE of this build step will mark the overall build as having WARNINGS. The remaining steps will still be executed.

alwaysRun: If True, this build step will always be run, even if a previous buildstep with haltOnFailure=True has failed.

description: This will be used to describe the command (on the Waterfall display) while the command is still running. It should be a single imperfect-tense verb, like compiling or testing. The preferred form is a single, short string, but for historical reasons a list of strings is also acceptable.

descriptionDone

This will be used to describe the command once it has finished. A simple noun like compile or tests should be used. Like description, this may either be a string or a list of short strings.

If neither description nor descriptionDone are set, the actual command arguments will be used to construct the description. This may be a bit too wide to fit comfortably on the Waterfall display.

All subclasses of BuildStep will contain the description attributes. Consequently, you could add a ShellCommand step like so:

from buildbot.plugins import steps

f.addStep(steps.ShellCommand(command=["make", "test"],
                             description="testing",
                             descriptionDone="tests"))

descriptionSuffix

This is an optional suffix appended to the end of the description (ie, after description and descriptionDone). This can be used to distinguish between build steps that would display the same descriptions in the waterfall. This parameter may be a string, a list of short strings or None.

For example, a builder might use the Compile step to build two different codebases. The descriptionSuffix could be set to projectFoo and projectBar, respectively for each step, which will result in the full descriptions compiling projectFoo and compiling projectBar to be shown in the waterfall.

doStepIf: A step can be configured to only run under certain conditions. To do this, set the step’s doStepIf to a boolean value, or to a function that returns a boolean value or Deferred. If the value or function result is false, then the step will return SKIPPED without doing anything. Otherwise, the step will be executed normally. If you set doStepIf to a function, that function should accept one parameter, which will be the BuildStep object itself.

hideStepIf

A step can be optionally hidden from the waterfall and build details web pages. To do this, set the step’s hideStepIf to a boolean value, or a function that takes two parameters (the results and the BuildStep) and returns a boolean value. Steps are always shown while they execute; however, after the step has finished, this parameter is evaluated (if it’s a function), and if the value is true, the step is hidden. For example, in order to hide the step if the step has been skipped:

factory.addStep(Foo(..., hideStepIf=lambda results, s: results==SKIPPED))

locks: A list of Locks (instances of buildbot.locks.WorkerLock or buildbot.locks.MasterLock) that should be acquired before starting this BuildStep. Alternatively, this could be a renderable that returns this list during build execution. This lets you defer picking the locks to acquire until the build step is about to start running. The Locks will be released when the step is complete. Note that this is a list of actual Lock instances, not names. Also note that all Locks must have unique names. See Interlocks.

logEncoding: The character encoding to use to decode logs produced during the execution of this step. This overrides the default logEncoding; see Log Handling.

updateBuildSummaryPolicy

The policy to use to propagate the step summary to the build summary. If False, the build summary will never include the step summary. If True, the build summary will always include the step summary. If set to a list (e.g. [FAILURE, EXCEPTION]), the step summary will be propagated if the step results id is present in that list. If not set or None, the default is computed according to other BuildStep parameters using following algorithm:

self.updateBuildSummaryPolicy = [EXCEPTION, RETRY, CANCELLED]
if self.flunkOnFailure or self.haltOnFailure or self.warnOnFailure:
    self.updateBuildSummaryPolicy.append(FAILURE)
if self.warnOnWarnings or self.flunkOnWarnings:
    self.updateBuildSummaryPolicy.append(WARNINGS)

Note that in a custom step, if BuildStep.getResultSummary is overridden and sets the build summary, updateBuildSummaryPolicy is ignored and the build summary will be used regardless.

2.5.12.2. Common Parameters of source checkout operations

All source checkout steps accept some common parameters to control how they get the sources and where they should be placed. The remaining per-VC-system parameters are mostly to specify where exactly the sources are coming from.

mode method

These two parameters specify the means by which the source is checked out. mode specifies the type of checkout and method tells about the way to implement it.
from buildbot.plugins import steps

factory = BuildFactory()
factory.addStep(steps.Mercurial(repourl='path/to/repo', mode='full',
                                method='fresh'))
The mode parameter a string describing the kind of VC operation that is desired (defaults to incremental). The options are:

incremental
Update the source to the desired revision, but do not remove any other files generated by previous builds. This allows compilers to take advantage of object files from previous builds. This mode is exactly same as the old update mode.

full
Update the source, but delete remnants of previous builds. Build steps that follow will need to regenerate all object files.

Methods are specific to the VC system in question, as they may take advantage of special behaviors in that VC system that can make checkouts more efficient or reliable.

workdir

Like all Steps, this indicates the directory where the build will take place. Source Steps are special in that they perform some operations outside of the workdir (like creating the workdir itself).

alwaysUseLatest

If True, bypass the usual behavior of checking out the revision in the source stamp, and always update to the latest revision in the repository instead. If the specific VC system supports branches and a specific branch is specified in the step parameters via branch or defaultBranch, then the latest revision on that branch is checked out.

retry

If set, this specifies a tuple of (delay, repeats) which means that when a full VC checkout fails, it should be retried up to repeats times, waiting delay seconds between the attempts. If you don’t provide this, it defaults to None, which means VC operations should not be retried. This is provided to make life easier for workers which are stuck behind poor network connections.

repository

The name of this parameter might vary depending on the Source step you are running. The concept explained here is common to all steps and applies to repourl as well as for baseURL (when applicable).

A common idiom is to pass Property('repository', 'url://default/repo/path') as repository. This grabs the repository from the source stamp of the build. This can be a security issue, if you allow force builds from the web, or have the WebStatus change hooks enabled; as the worker will download code from an arbitrary repository.

codebase

This specifies which codebase the source step should use to select the right source stamp. The default codebase value is ''. The codebase must correspond to a codebase assigned by the codebaseGenerator. If there is no codebaseGenerator defined in the master, then codebase doesn’t need to be set; the default value will match all changes.

timeout

Specifies the timeout for worker-side operations, in seconds. If your repositories are particularly large, then you may need to increase this value from the default of 1200 (20 minutes).

logEnviron

If this option is true (the default), then the step’s logfile will describe the environment variables on the worker. In situations where the environment is not relevant and is long, it may be easier to set logEnviron=False.

env

A dictionary of environment strings which will be added to the child command’s environment. The usual property interpolations can be used in environment variable names and values - see Properties.

2.5.12.3. Bzr

class buildbot.steps.source.bzr.Bzr

bzr is a descendant of Arch/Baz, and is frequently referred to as simply Bazaar. The repository-vs-workspace model is similar to Darcs, but it uses a strictly linear sequence of revisions (one history per branch) like Arch. Branches are put in subdirectories. This makes it look very much like Mercurial.

from buildbot.plugins import steps

factory.addStep(steps.Bzr(mode='incremental',
                          repourl='lp:~knielsen/maria/tmp-buildbot-test'))

The step takes the following arguments:

repourl: (required unless baseURL is provided): the URL at which the Bzr source repository is available.
baseURL: (required unless repourl is provided): the base repository URL, to which a branch name will be appended. It should probably end in a slash.
defaultBranch: (allowed if and only if baseURL is provided): this specifies the name of the branch to use when a Build does not provide one of its own. This will be appended to baseURL to create the string that will be passed to the bzr checkout command. If alwaysUseLatest is True then the branch and revision information that comes with the Build is ignored and branch specified in this parameter is used.

mode method

No method is needed for incremental mode. For full mode, method can take the values shown below. If no value is given, it defaults to fresh.

clobber
This specifies to remove the workdir and make a full checkout.

fresh
This method first runs bzr clean-tree to remove all the unversioned files then update the repo. This remove all unversioned files including those in .bzrignore.

clean
This is same as fresh except that it doesn’t remove the files mentioned in .bzrginore i.e, by running bzr clean-tree --ignore.

copy
A local bzr repository is maintained and the repo is copied to build directory for each build. Before each build the local bzr repo is updated then copied to build for next steps.

2.5.12.4. CVS

class buildbot.steps.source.cvs.CVS

The CVS build step performs a CVS checkout or update.

from buildbot.plugins import steps

factory.addStep(steps.CVS(mode='incremental',
                cvsroot=':pserver:me@cvs.example.net:/cvsroot/myproj',
                cvsmodule='buildbot'))

This step takes the following arguments:

cvsroot: (required): specify the CVSROOT value, which points to a CVS repository, probably on a remote machine. For example, if Buildbot was hosted in CVS then the CVSROOT value you would use to get a copy of the Buildbot source code might be :pserver:anonymous@cvs.example.net:/cvsroot/buildbot.
cvsmodule: (required): specify the cvs module, which is generally a subdirectory of the CVSROOT. The cvsmodule for the Buildbot source code is buildbot.
branch: a string which will be used in a -r argument. This is most useful for specifying a branch to work on. Defaults to HEAD. If alwaysUseLatest is True then the branch and revision information that comes with the Build is ignored and branch specified in this parameter is used.
global_options: a list of flags to be put before the argument checkout in the CVS command.
extra_options: a list of flags to be put after the checkout in the CVS command.

mode method

No method is needed for incremental mode. For full mode, method can take the values shown below. If no value is given, it defaults to fresh.

clobber
This specifies to remove the workdir and make a full checkout.

fresh
This method first runs cvsdisard in the build directory, then updates it. This requires cvsdiscard which is a part of the cvsutil package.

clean
This method is the same as method='fresh', but it runs cvsdiscard --ignore instead of cvsdiscard.

copy
This maintains a source directory for source, which it updates copies to the build directory. This allows Buildbot to start with a fresh directory, without downloading the entire repository on every build.

login: Password to use while performing login to the remote CVS server. Default is None meaning that no login needs to be performed.

2.5.12.5. Darcs

class buildbot.steps.source.darcs.Darcs

The Darcs build step performs a Darcs checkout or update.

from buildbot.plugins import steps

factory.addStep(steps.Darcs(repourl='http://path/to/repo',
                            mode='full', method='clobber', retry=(10, 1)))

Darcs step takes the following arguments:

repourl: (required): The URL at which the Darcs source repository is available.

mode

(optional): defaults to 'incremental'. Specifies whether to clean the build tree or not.

incremental
The source is update, but any built files are left untouched.

full
The build tree is clean of any built files. The exact method for doing this is controlled by the method argument.

method

(optional): defaults to copy when mode is full. Darcs’ incremental mode does not require a method. The full mode has two methods defined:

clobber: It removes the working directory for each build then makes full checkout.
copy: This first checkout source into source directory then copy the source directory to build directory then performs the build operation in the copied directory. This way we make fresh builds with very less bandwidth to download source. The behavior of source checkout follows exactly same as incremental. It performs all the incremental checkout behavior in source directory.

2.5.12.6. Gerrit

class buildbot.steps.source.gerrit.Gerrit

Gerrit step is exactly like the Git step, except that it integrates with GerritChangeSource, and will automatically checkout the additional changes.

Gerrit integration can be also triggered using forced build with property named gerrit_change with values in format change_number/patchset_number. This property will be translated into a branch name. This feature allows integrators to build with several pending interdependent changes, which at the moment cannot be described properly in Gerrit, and can only be described by humans.

2.5.12.7. GitHub

class buildbot.steps.source.github.GitHub

GitHub step is exactly like the Git step, except that it will ignore the revision sent by the GitHub change hook, and rather take the branch if the branch ends with /merge.

This allows to test github pull requests merged directly into the mainline.

GitHub indeed provides refs/origin/pull/NNN/merge on top of refs/origin/pull/NNN/head which is a magic ref that always creates a merge commit to the latest version of the mainline (i.e., the target branch for the pull request).

The revision in the GitHub event points to /head, and it’s important for the GitHub reporter as this is the revision that will be tagged with a CI status when the build is finished.

If you want to use Trigger to create sub tests and want to have the GitHub reporter still update the original revision, make sure you set updateSourceStamp=False in the Trigger configuration.

2.5.12.8. GitLab

class buildbot.steps.source.gitlab.GitLab

GitLab step is exactly like the Git step, except that it uses the source repo and branch sent by the GitLab change hook when processing merge requests.

When configuring builders, you can use a ChangeFilter with category = "push" to select normal commits, and category = "merge_request" to select merge requests.

See master/docs/examples/gitlab.cfg in the Buildbot distribution for a tutorial example of integrating Buildbot with GitLab.

Note

Your build worker will need access to the source project of the changeset, or it won’t be able to check out the source. This means authenticating the build worker via ssh credentials in the usual way, then granting it access [via a GitLab deploy key or GitLab project membership](https://docs.gitlab.com/ee/ssh/). This needs to be done not only for the main git repo, but also for each fork that wants to be able to submit merge requests against the main repo.

2.5.12.9. Git

class buildbot.steps.source.git.Git

The Git build step clones or updates a Git repository and checks out the specified branch or revision.

Note

Buildbot supports Git version 1.2.0 or later.

from buildbot.plugins import steps

factory.addStep(steps.Git(repourl='git://path/to/repo', mode='full',
                          method='clobber', submodules=True))

The Git step takes the following arguments:

repourl (required)

The URL of the upstream Git repository.

branch (optional)

This specifies the name of the branch or the tag to use when a Build does not provide one of its own. If this parameter is not specified, and the Build does not provide a branch, the default branch of the remote repository will be used. If alwaysUseLatest is True then the branch and revision information that comes with the Build is ignored and the branch specified in this parameter is used.

submodules (optional, default: False)

When initializing/updating a Git repository, this tells Buildbot whether to handle Git submodules. If remoteSubmodules is True, then this tells Buildbot to use remote submodules: Git Remote Submodules

tags (optional, default: False)

Download tags in addition to the requested revision when updating repository.

shallow (optional)

Instructs Git to attempt shallow clones (--depth 1). The depth defaults to 1 and can be changed by passing an integer instead of True. This option can be used only in incremental builds, or full builds with clobber method.

reference (optional)

Use the specified string as a path to a reference repository on the local machine. Git will try to grab objects from this path first instead of the main repository, if they exist.

origin (optional)

By default, any clone will use the name “origin” as the remote repository (eg, “origin/master”). This renderable option allows that to be configured to an alternate name.

filters (optional, type: list)

For each string in the passed in list, adds a --filter <filter> argument to git clone. This allows for adding filters like --filter "tree:0" to speed up the clone step. This requires git version 2.27 or higher.

progress (optional)

Passes the (--progress) flag to (git fetch). This solves issues of long fetches being killed due to lack of output, but requires Git 1.7.2 or later. Its value is True on Git 1.7.2 or later.

retryFetch (optional, default: False)

If true, if the git fetch fails, then Buildbot retries to fetch again instead of failing the entire source checkout.

clobberOnFailure (optional, default: False)

If a fetch or full clone fails, we can retry to checkout the source by removing everything and cloning the repository. If the retry fails, it fails the source checkout step.

mode (optional, default: 'incremental')

Specifies whether to clean the build tree or not.

incremental: The source is update, but any built files are left untouched.
full: The build tree is clean of any built files. The exact method for doing this is controlled by the method argument.

method (optional, default: fresh when mode is full)

Git’s incremental mode does not require a method. The full mode has four methods defined:

clobber: It removes the build directory entirely then makes full clone from repo. This can be slow as it need to clone whole repository. To make faster clones enable the shallow option. If the shallow option is enabled and the build request has unknown revision value, then this step fails.
fresh: This removes all other files except those tracked by Git. First it does git clean -d -f -f -x, then fetch/checkout to a specified revision (if any). This option is equal to update mode with ignore_ignores=True in old steps.
clean: All the files which are tracked by Git, as well as listed ignore files, are not deleted. All other remaining files will be deleted before the fetch/checkout. This is equivalent to git clean -d -f -f then fetch. This is equivalent to ignore_ignores=False in old steps.
copy: This first checks out source into source directory, then copies the source directory to build directory, and then performs the build operation in the copied directory. This way, we make fresh builds with very little bandwidth to download source. The behavior of source checkout follows exactly the same as incremental. It performs all the incremental checkout behavior in source directory.

getDescription (optional)

After checkout, invoke a git describe on the revision and save the result in a property; the property’s name is either commit-description or commit-description-foo, depending on whether the codebase argument was also provided. The argument should either be a bool or dict, and will change how git describe is called:

getDescription=False: disables this feature explicitly
getDescription=True or empty {}: runs git describe with no args
getDescription={...}: a dict with keys named the same as the Git option. Each key’s value can be False or None to explicitly skip that argument.

For the following keys, a value of True appends the same-named Git argument:
- all : –all
- always: –always
- contains: –contains
- debug: –debug
- long: –long`
- exact-match: –exact-match
- tags: –tags
- dirty: –dirty
For the following keys, an integer or string value (depending on what Git expects) will set the argument’s parameter appropriately. Examples show the key-value pair:
- match=foo: –match foo
- abbrev=7: –abbrev=7
- candidates=7: –candidates=7
- dirty=foo: –dirty=foo

config (optional)

A dict of Git configuration settings to pass to the remote Git commands.

sshPrivateKey (optional)

The private key to use when running Git for fetch operations. The ssh utility must be in the system path in order to use this option. On Windows, only Git distribution that embeds MINGW has been tested (as of July 2017, the official distribution is MINGW-based). The worker must either have the host in the known hosts file or the host key must be specified via the sshHostKey option.

sshHostKey (optional)

sshKnownHosts (optional)

2.5.12.10. Mercurial

class buildbot.steps.source.mercurial.Mercurial

The Mercurial build step performs a Mercurial (aka hg) checkout or update.

Branches are available in two modes: dirname, where the name of the branch is a suffix of the name of the repository, or inrepo, which uses Hg’s named-branches support. Make sure this setting matches your changehook, if you have that installed.

from buildbot.plugins import steps

factory.addStep(steps.Mercurial(repourl='path/to/repo', mode='full',
                                method='fresh', branchType='inrepo'))

The Mercurial step takes the following arguments:

repourl: where the Mercurial source repository is available.
defaultBranch: this specifies the name of the branch to use when a Build does not provide one of its own. This will be appended to repourl to create the string that will be passed to the hg clone command. If alwaysUseLatest is True then the branch and revision information that comes with the Build is ignored and branch specified in this parameter is used.
branchType: either ‘dirname’ (default) or ‘inrepo’ depending on whether the branch name should be appended to the repourl or the branch is a Mercurial named branch and can be found within the repourl.
clobberOnBranchChange: boolean, defaults to True. If set and using inrepos branches, clobber the tree at each branch change. Otherwise, just update to the branch.

mode method

Mercurial’s incremental mode does not require a method. The full mode has three methods defined:

clobber
It removes the build directory entirely then makes full clone from repo. This can be slow as it need to clone whole repository

fresh
This remove all other files except those tracked by VCS. First it does hg purge --all then pull/update

clean
All the files which are tracked by Mercurial and listed ignore files are not deleted. Remaining all other files will be deleted before pull/update. This is equivalent to hg purge then pull/update.

2.5.12.11. Monotone

class buildbot.steps.source.mtn.Monotone

The Monotone build step performs a Monotone checkout or update.

from buildbot.plugins import steps

factory.addStep(steps.Monotone(repourl='http://path/to/repo',
                               mode='full', method='clobber',
                               branch='some.branch.name', retry=(10, 1)))

Monotone step takes the following arguments:

repourl: the URL at which the Monotone source repository is available.
branch: this specifies the name of the branch to use when a Build does not provide one of its own. If alwaysUseLatest is True then the branch and revision information that comes with the Build is ignored and branch specified in this parameter is used.
progress: this is a boolean that has a pull from the repository use --ticker=dot instead of the default --ticker=none.

mode

(optional): defaults to 'incremental'. Specifies whether to clean the build tree or not. In any case, the worker first pulls from the given remote repository to synchronize (or possibly initialize) its local database. The mode and method only affect how the build tree is checked-out or updated from the local database.

incremental
The source is update, but any built files are left untouched.

full
The build tree is clean of any built files. The exact method for doing this is controlled by the method argument. Even in this mode, the revisions already pulled remain in the database and a fresh pull is rarely needed.

method

(optional): defaults to copy when mode is full. Monotone’s incremental mode does not require a method. The full mode has four methods defined:

clobber
It removes the build directory entirely then makes fresh checkout from the database.

clean
This remove all other files except those tracked and ignored by Monotone. It will remove all the files that appear in mtn ls unknown. Then it will pull from remote and update the working directory.

fresh
This remove all other files except those tracked by Monotone. It will remove all the files that appear in mtn ls ignored and mtn ls unknows. Then pull and update similar to clean

copy
This first checkout source into source directory then copy the source directory to build directory then performs the build operation in the copied directory. This way we make fresh builds with very less bandwidth to download source. The behavior of source checkout follows exactly same as incremental. It performs all the incremental checkout behavior in source directory.

2.5.12.12. P4

class buildbot.steps.source.p4.P4

The P4 build step creates a Perforce client specification and performs an update.

from buildbot.plugins import steps, util

factory.addStep(steps.P4(
    p4port=p4port,
    p4client=util.WithProperties('%(P4USER)s-%(workername)s-%(buildername)s'),
    p4user=p4user,
    p4base='//depot',
    p4viewspec=p4viewspec,
    mode='incremental'))

You can specify the client spec in two different ways. You can use the p4base, p4branch, and (optionally) p4extra_views to build up the viewspec, or you can utilize the p4viewspec to specify the whole viewspec as a set of tuples.

Using p4viewspec will allow you to add lines such as:

//depot/branch/mybranch/...             //<p4client>/...
-//depot/branch/mybranch/notthisdir/... //<p4client>/notthisdir/...

If you specify p4viewspec and any of p4base, p4branch, and/or p4extra_views you will receive a configuration error exception.

p4base

A view into the Perforce depot without branch name or trailing /.... Typically //depot/proj.

p4branch

(optional): A single string, which is appended to the p4base as follows <p4base>/<p4branch>/... to form the first line in the viewspec

p4extra_views

(optional): a list of (depotpath, clientpath) tuples containing extra views to be mapped into the client specification. Both will have /... appended automatically. The client name and source directory will be prepended to the client path.

p4viewspec

This will override any p4branch, p4base, and/or p4extra_views specified. The viewspec will be an array of tuples as follows:

[('//depot/main/','')]

It yields a viewspec with just:

//depot/main/... //<p4client>/...

p4viewspec_suffix

(optional): The p4viewspec lets you customize the client spec for a builder but, as the previous example shows, it automatically adds ... at the end of each line. If you need to also specify file-level remappings, you can set the p4viewspec_suffix to None so that nothing is added to your viewspec:

[('//depot/main/...', '...'),
 ('-//depot/main/config.xml', 'config.xml'),
 ('//depot/main/config.vancouver.xml', 'config.xml')]

It yields a viewspec with:

//depot/main/...                  //<p4client>/...
-//depot/main/config.xml          //<p4client/main/config.xml
//depot/main/config.vancouver.xml //<p4client>/main/config.xml

Note how, with p4viewspec_suffix set to None, you need to manually add ... where you need it.

p4client_spec_options

(optional): By default, clients are created with the allwrite rmdir options. This string lets you change that.

p4port

(optional): the host:port string describing how to get to the P4 Depot (repository), used as the option -p argument for all p4 commands.

p4user

(optional): the Perforce user, used as the option -u argument to all p4 commands.

p4passwd

(optional): the Perforce password, used as the option -p argument to all p4 commands.

p4client

(optional): The name of the client to use. In mode='full' and mode='incremental', it’s particularly important that a unique name is used for each checkout directory to avoid incorrect synchronization. For this reason, Python percent substitution will be performed on this value to replace %(prop:workername)s with the worker name and %(prop:buildername)s with the builder name. The default is buildbot_%(prop:workername)s_%(prop:buildername)s.

p4line_end

(optional): The type of line ending handling P4 should use. This is added directly to the client spec’s LineEnd property. The default is local.

p4client_type

(optional): The type of client to create. A client type can be set to create a client better suited to CI use. Learn more about client type in the P4 documentation The default is None.

p4extra_args

(optional): Extra arguments to be added to the P4 command-line for the sync command. So for instance if you want to sync only to populate a Perforce proxy (without actually syncing files to disk), you can do:

P4(p4extra_args=['-Zproxyload'], ...)

use_tickets

Set to True to use ticket-based authentication, instead of passwords (but you still need to specify p4passwd).

stream

Set to True to use a stream-associated workspace, in which case p4base and p4branch are used to determine the stream path.

2.5.12.13. Repo

class buildbot.steps.source.repo.Repo

The Repo build step performs a Repo init and sync.

The Repo step takes the following arguments:

manifestURL

(required): the URL at which the Repo’s manifests source repository is available.

manifestBranch

(optional, defaults to master): the manifest repository branch on which repo will take its manifest. Corresponds to the -b argument to the repo init command.

manifestFile

(optional, defaults to default.xml): the manifest filename. Corresponds to the -m argument to the repo init command.

tarball

(optional, defaults to None): the repo tarball used for fast bootstrap. If not present the tarball will be created automatically after first sync. It is a copy of the .repo directory which contains all the Git objects. This feature helps to minimize network usage on very big projects with lots of workers.

The suffix of the tarball determines if the tarball is compressed and which compressor is chosen. Supported suffixes are bz2, gz, lzma, lzop, and pigz.

jobs

(optional, defaults to None): Number of projects to fetch simultaneously while syncing. Passed to repo sync subcommand with “-j”.

syncAllBranches

(optional, defaults to False): renderable boolean to control whether repo syncs all branches. I.e. repo sync -c

depth

(optional, defaults to 0): Depth argument passed to repo init. Specifies the amount of git history to store. A depth of 1 is useful for shallow clones. This can save considerable disk space on very large projects.

submodules

(optional, defaults to False): sync any submodules associated with the manifest repo. Corresponds to the --submodules argument to the repo init command.

updateTarballAge

(optional, defaults to “one week”): renderable to control the policy of updating of the tarball given properties. Returns: max age of tarball in seconds, or None, if we want to skip tarball update. The default value should be good trade off on size of the tarball, and update frequency compared to cost of tarball creation

repoDownloads

(optional, defaults to None): list of repo download commands to perform at the end of the Repo step each string in the list will be prefixed repo download, and run as is. This means you can include parameter in the string. For example:

["-c project 1234/4"] will cherry-pick patchset 4 of patch 1234 in project project
["-f project 1234/4"] will enforce fast-forward on patchset 4 of patch 1234 in project project

class buildbot.steps.source.repo.RepoDownloadsFromProperties

util.repo.DownloadsFromProperties can be used as a renderable of the repoDownload parameter it will look in passed properties for string with following possible format:

repo download project change_number/patchset_number
project change_number/patchset_number
project/change_number/patchset_number

All of these properties will be translated into a repo download. This feature allows integrators to build with several pending interdependent changes, which at the moment cannot be described properly in Gerrit, and can only be described by humans.

class buildbot.steps.source.repo.RepoDownloadsFromChangeSource

util.repo.DownloadsFromChangeSource can be used as a renderable of the repoDownload parameter

This rendereable integrates with GerritChangeSource, and will automatically use the repo download command of repo to download the additional changes introduced by a pending changeset.

Note

You can use the two above Rendereable in conjunction by using the class buildbot.process.properties.FlattenList

For example:

from buildbot.plugins import steps, util

factory.addStep(steps.Repo(manifestURL='git://gerrit.example.org/manifest.git',
                           repoDownloads=util.FlattenList([
                                util.RepoDownloadsFromChangeSource(),
                                util.RepoDownloadsFromProperties("repo_downloads")
                           ])))

2.5.12.14. SVN

class buildbot.steps.source.svn.SVN

The SVN build step performs a Subversion checkout or update. There are two basic ways of setting up the checkout step, depending upon whether you are using multiple branches or not.

The SVN step should be created with the repourl argument:

repourl: (required): this specifies the URL argument that will be given to the svn checkout command. It dictates both where the repository is located and which sub-tree should be extracted. One way to specify the branch is to use Interpolate. For example, if you wanted to check out the trunk repository, you could use repourl=Interpolate("http://svn.example.com/repos/%(src::branch)s"). Alternatively, if you are using a remote Subversion repository which is accessible through HTTP at a URL of http://svn.example.com/repos, and you wanted to check out the trunk/calc sub-tree, you would directly use repourl="http://svn.example.com/repos/trunk/calc" as an argument to your SVN step.

If you are building from multiple branches, then you should create the SVN step with the repourl and provide branch information with Interpolate:

from buildbot.plugins import steps, util

factory.addStep(
    steps.SVN(mode='incremental',
              repourl=util.Interpolate(
                  'svn://svn.example.org/svn/%(src::branch)s/myproject')))

Alternatively, the repourl argument can be used to create the SVN step without Interpolate:

from buildbot.plugins import steps

factory.addStep(steps.SVN(mode='full',
                repourl='svn://svn.example.org/svn/myproject/trunk'))

username

(optional): if specified, this will be passed to the svn binary with a --username option.

password

(optional): if specified, this will be passed to the svn binary with a --password option.

extra_args

(optional): if specified, an array of strings that will be passed as extra arguments to the svn binary.

keep_on_purge

(optional): specific files or directories to keep between purges, like some build outputs that can be reused between builds.

depth

(optional): Specify depth argument to achieve sparse checkout. Only available if worker has Subversion 1.5 or higher.

If set to empty updates will not pull in any files or subdirectories not already present. If set to files, updates will pull in any files not already present, but not directories. If set to immediates, updates will pull in any files or subdirectories not already present, the new subdirectories will have depth: empty. If set to infinity, updates will pull in any files or subdirectories not already present; the new subdirectories will have depth-infinity. Infinity is equivalent to SVN default update behavior, without specifying any depth argument.

preferLastChangedRev

(optional): By default, the got_revision property is set to the repository’s global revision (“Revision” in the svn info output). Set this parameter to True to have it set to the “Last Changed Rev” instead.

mode method

SVN’s incremental mode does not require a method. The full mode has five methods defined:

clobber
It removes the working directory for each build then makes full checkout.

fresh
This always always purges local changes before updating. This deletes unversioned files and reverts everything that would appear in a svn status --no-ignore. This is equivalent to the old update mode with always_purge.

clean
This is same as fresh except that it deletes all unversioned files generated by svn status.

copy
This first checkout source into source directory then copy the source directory to build directory then performs the build operation in the copied directory. This way we make fresh builds with very less bandwidth to download source. The behavior of source checkout follows exactly same as incremental. It performs all the incremental checkout behavior in source directory.

export
Similar to method='copy', except using svn export to create build directory so that there are no .svn directories in the build directory.

If you are using branches, you must also make sure your ChangeSource will report the correct branch names.

2.5.12.15. GitCommit

class buildbot.steps.source.git.GitCommit

The GitCommit build step adds files and commits modifications in your local Git repository.

The GitCommit step takes the following arguments:

workdir: (required) The path to the local repository to push commits from.
messages: (required) List of message that will be created with the commit. Correspond to the -m flag of the git commit command.
paths: (required) List of path that will be added to the commit.
logEnviron: (optional) If this option is true (the default), then the step’s logfile will describe the environment variables on the worker. In situations where the environment is not relevant and is long, it may be easier to set logEnviron=False.
env: (optional) A dictionary of environment strings which will be added to the child command’s environment. The usual property interpolations can be used in environment variable names and values - see Properties.
timeout: (optional) Specifies the timeout for worker-side operations, in seconds. If your repositories are particularly large, then you may need to increase this value from its default of 1200 (20 minutes).
config: (optional) A dict of git configuration settings to pass to the remote git commands.
no_verify: (optional) Specifies whether --no-verify option should be supplied to git. The default is False.
emptyCommits: (optional) One of the values disallow (default), create-empty-commit, and ignore. Decides the behavior when there is nothing to be committed. The value disallow will make the buildstep fail. The value create-empty-commit will create an empty commit. The value ignore will create no commit.

2.5.12.16. GitTag

class buildbot.steps.source.git.GitTag

The GitTag build step creates a tag in your local Git repository.

The GitTag step takes the following arguments:

workdir: (required) The path to the local repository to push commits from.
tagName: (required) The name of the tag.
annotated: (optional) If True, create an annotated tag.
messages: (optional) List of message that will be created with the annotated tag. Must be set only if annotated parameter is True. Correspond to the -m flag of the git tag command.
force: (optional) If True, forces overwrite of tags on the local repository. Corresponds to the --force flag of the git tag command.
logEnviron: (optional) If this option is true (the default), then the step’s logfile will describe the environment variables on the worker. In situations where the environment is not relevant and is long, it may be easier to set logEnviron=False.
env: (optional) A dictionary of environment strings which will be added to the child command’s environment. The usual property interpolations can be used in environment variable names and values - see Properties.
timeout: (optional) Specifies the timeout for worker-side operations, in seconds. If your repositories are particularly large, then you may need to increase this value from its default of 1200 (20 minutes).
config: (optional) A dict of git configuration settings to pass to the remote git commands.

2.5.12.17. GitPush

class buildbot.steps.source.git.GitPush

The GitPush build step pushes new commits to a Git repository.

The GitPush step takes the following arguments:

workdir: (required) The path to the local repository to push commits from.
repourl: (required) The URL of the upstream Git repository.
branch: (required) The branch to push. The branch should already exist on the local repository.
force: (optional) If True, forces overwrite of refs on the remote repository. Corresponds to the --force flag of the git push command.
logEnviron: (optional) If this option is true (the default), then the step’s logfile will describe the environment variables on the worker. In situations where the environment is not relevant and is long, it may be easier to set logEnviron=False.
env: (optional) A dictionary of environment strings which will be added to the child command’s environment. The usual property interpolations can be used in environment variable names and values - see Properties.
timeout: (optional) Specifies the timeout for worker-side operations, in seconds. If your repositories are particularly large, then you may need to increase this value from its default of 1200 (20 minutes).

config

(optional) A dict of git configuration settings to pass to the remote git commands.

sshPrivateKey

(optional) The private key to use when running git for fetch operations. The ssh utility must be in the system path in order to use this option. On Windows only git distribution that embeds MINGW has been tested (as of July 2017 the official distribution is MINGW-based). The worker must either have the host in the known hosts file or the host key must be specified via the sshHostKey option.

sshHostKey

(optional) Specifies public host key to match when authenticating with SSH public key authentication. This may be either a Secret or just a string. sshPrivateKey must be specified in order to use this option. The host key must be in the form of <key type> <base64-encoded string>, e.g. ssh-rsa AAAAB3N<...>FAaQ==.

sshKnownHosts (optional): Specifies the contents of the SSH known_hosts file to match when authenticating with SSH public key authentication. This may be either a Secret or just a string. sshPrivateKey must be specified in order to use this option. sshHostKey must not be specified in order to use this option.

2.5.12.18. GitDiffInfo

The GitDiffInfo step gathers information about differences between the current revision and the last common ancestor of this revision and another commit or branch. This information is useful for various reporters to be able to identify new warnings that appear in newly modified code. The diff information is stored as a custom json as transient build data via setBuildData function.

Currently only git repositories are supported.

The class inherits the arguments accepted by ShellMixin except command.

Additionally, it accepts the following arguments:

compareToRef: (Optional, string, defaults to master) The commit or branch identifying the revision to get the last common ancestor to. In most cases, this will be the target branch of a pull or merge request.
dataName: (Optional, string, defaults to diffinfo-master) The name of the build data to save the diff json to.

Build data specification

This section documents the format of the data produced by the GitDiffInfo step and put into build data. Any future steps performing the same operation on different version control systems should produce data in the same format. Likewise, all consumers should expect the input data to be in the format as documented here.

Conceptually, the diffinfo data is a list of file changes, each of which itself contain a list of diff hunks within that file.

This data is stored as a JSON document.

The root element is a list of objects, each of which represent a file where changes have been detected. Each of these file objects has the following keys:

source_file - a string representing path to the source file. This does not include any prefixes such as a/. When there is no source file, e.g. when a new file is created, /dev/null is used.
target_file - a string representing path to the target file. This does not include any prefixes such as b/. When there is no target file, e.g. when a file has been deleted, /dev/null is used.
is_binary - a boolean specifying whether this is a binary file or not. Changes in binary files are not interpreted as hunks.
is_rename - a boolean specifying whether this file has been renamed
hunks - a list of objects (described below) specifying individual changes within the file.

Each of the hunk objects has the following keys:

ss - an integer specifying the start line of the diff hunk in the source file
sl - an integer specifying the length of the hunk in the source file as a number of lines
ts - an integer specifying the start line of the diff hunk in the target file
tl - an integer specifying the length of the hunk in the target file as a number lines

Example of produced build data

The following shows build data that is produced for a deleted file, a changed file and a new file.

[
  {
    "source_file": "file1",
    "target_file": "/dev/null",
    "is_binary": false,
    "is_rename": false,
    "hunks": [
      {
        "ss": 1,
        "sl": 3,
        "ts": 0,
        "tl": 0
      }
    ]
  },
  {
    "source_file": "file2",
    "target_file": "file2",
    "is_binary": false,
    "is_rename": false,
    "hunks": [
      {
        "ss": 4,
        "sl": 0,
        "ts": 5,
        "tl": 3
      },
      {
        "ss": 15,
        "sl": 0,
        "ts": 19,
        "tl": 3
      }
    ]
  },
  {
    "source_file": "/dev/null",
    "target_file": "file3",
    "is_binary": false,
    "is_rename": false,
    "hunks": [
      {
        "ss": 0,
        "sl": 0,
        "ts": 1,
        "tl": 3
      }
    ]
  }
]

2.5.12.19. ShellCommand

Most interesting steps involve executing a process of some sort on the worker. The ShellCommand class handles this activity.

Several subclasses of ShellCommand are provided as starting points for common build steps.

Using ShellCommands

class buildbot.steps.shell.ShellCommand

This is a useful base class for just about everything you might want to do during a build (except for the initial source checkout). It runs a single command in a child shell on the worker. All stdout/stderr is recorded into a LogFile. The step usually finishes with a status of FAILURE if the command’s exit code is non-zero, otherwise it has a status of SUCCESS.

The preferred way to specify the command is with a list of argv strings, since this allows for spaces in filenames and avoids doing any fragile shell-escaping. You can also specify the command with a single string, in which case the string is given to /bin/sh -c COMMAND for parsing.

On Windows, commands are run via cmd.exe /c which works well. However, if you’re running a batch file, the error level does not get propagated correctly unless you add ‘call’ before your batch file’s name: cmd=['call', 'myfile.bat', ...].

The ShellCommand arguments are:

command

A list of strings (preferred) or single string (discouraged) which specifies the command to be run. A list of strings is preferred because it can be used directly as an argv array. Using a single string (with embedded spaces) requires the worker to pass the string to /bin/sh for interpretation, which raises all sorts of difficult questions about how to escape or interpret shell metacharacters.

If command contains nested lists (for example, from a properties substitution), then that list will be flattened before it is executed.

workdir

All ShellCommands are run by default in the workdir, which defaults to the build subdirectory of the worker builder’s base directory. The absolute path of the workdir will thus be the worker’s basedir (set as an option to buildbot-worker create-worker, Creating a worker), plus the builder’s basedir (set in the builder’s builddir key in master.cfg), plus the workdir itself (a class-level attribute of the BuildFactory, defaults to build).

For example:

from buildbot.plugins import steps

f.addStep(steps.ShellCommand(command=["make", "test"],
                             workdir="build/tests"))

env

A dictionary of environment strings which will be added to the child command’s environment. For example, to run tests with a different i18n language setting, you might use:

from buildbot.plugins import steps

f.addStep(steps.ShellCommand(command=["make", "test"],
                             env={'LANG': 'fr_FR'}))

These variable settings will override any existing ones in the worker’s environment or the environment specified in the Builder. The exception is PYTHONPATH, which is merged with (actually prepended to) any existing PYTHONPATH setting. The following example will prepend /home/buildbot/lib/python to any existing PYTHONPATH:

from buildbot.plugins import steps

f.addStep(steps.ShellCommand(
              command=["make", "test"],
              env={'PYTHONPATH': "/home/buildbot/lib/python"}))

To avoid the need of concatenating paths together in the master config file, if the value is a list, it will be joined together using the right platform dependent separator.

Those variables support expansion so that if you just want to prepend /home/buildbot/bin to the PATH environment variable, you can do it by putting the value ${PATH} at the end of the value like in the example below. Variables that don’t exist on the worker will be replaced by "".

from buildbot.plugins import steps

f.addStep(steps.ShellCommand(
              command=["make", "test"],
              env={'PATH': ["/home/buildbot/bin",
                            "${PATH}"]}))

Note that environment values must be strings (or lists that are turned into strings). In particular, numeric properties such as buildnumber must be substituted using Interpolate.

want_stdout

If False, stdout from the child process is discarded rather than being sent to the buildmaster for inclusion in the step’s LogFile.

want_stderr

Like want_stdout but for stderr. Note that commands that run through a PTY do not have separate stdout/stderr streams, and both are merged into stdout.

usePTY

If True, this command will be run in a pty (defaults to False). This option is not available on Windows.

In general, you do not want to use a pseudo-terminal. This is only useful for running commands that require a terminal - for example, testing a command-line application that will only accept passwords read from a terminal. Using a pseudo-terminal brings lots of compatibility problems, and prevents Buildbot from distinguishing the standard error (red) and standard output (black) streams.

In previous versions, the advantage of using a pseudo-terminal was that grandchild processes were more likely to be cleaned up if the build was interrupted or it timed out. This occurred because using a pseudo-terminal incidentally puts the command into its own process group.

As of Buildbot-0.8.4, all commands are placed in process groups, and thus grandchild processes will be cleaned up properly.

logfiles

Sometimes commands will log interesting data to a local file, rather than emitting everything to stdout or stderr. For example, Twisted’s trial command (which runs unit tests) only presents summary information to stdout, and puts the rest into a file named _trial_temp/test.log. It is often useful to watch these files as the command runs, rather than using /bin/cat to dump their contents afterwards.

The logfiles= argument allows you to collect data from these secondary logfiles in near-real-time, as the step is running. It accepts a dictionary which maps from a local Log name (which is how the log data is presented in the build results) to either a remote filename (interpreted relative to the build’s working directory), or a dictionary of options. Each named file will be polled on a regular basis (every couple of seconds) as the build runs, and any new text will be sent over to the buildmaster.

If you provide a dictionary of options instead of a string, you must specify the filename key. You can optionally provide a follow key which is a boolean controlling whether a logfile is followed or concatenated in its entirety. Following is appropriate for logfiles to which the build step will append, where the pre-existing contents are not interesting. The default value for follow is False, which gives the same behavior as just providing a string filename.

from buildbot.plugins import steps

f.addStep(steps.ShellCommand(
                   command=["make", "test"],
                   logfiles={"triallog": "_trial_temp/test.log"}))

The above example will add a log named ‘triallog’ on the master, based on _trial_temp/test.log on the worker.

from buildbot.plugins import steps

f.addStep(steps.ShellCommand(command=["make", "test"],
                             logfiles={
                                 "triallog": {
                                    "filename": "_trial_temp/test.log",
                                    "follow": True
                                 }
                             }))

lazylogfiles

If set to True, logfiles will be tracked lazily, meaning that they will only be added when and if something is written to them. This can be used to suppress the display of empty or missing log files. The default is False.

timeout

If the command fails to produce any output for this many seconds, it is assumed to be locked up and will be killed. This defaults to 1200 seconds. Pass None to disable.

maxTime

If the command takes longer than this many seconds, it will be killed. This is disabled by default.

logEnviron

If True (the default), then the step’s logfile will describe the environment variables on the worker. In situations where the environment is not relevant and is long, it may be easier to set it to False.

interruptSignal

This is the signal (specified by name) that should be sent to the process when the command needs to be interrupted (either by the buildmaster, a timeout, etc.). By default, this is “KILL” (9). Specify “TERM” (15) to give the process a chance to cleanup. This functionality requires a version 0.8.6 worker or newer.

sigtermTime

If set, when interrupting, try to kill the command with SIGTERM and wait for sigtermTime seconds before firing interuptSignal. If None, interruptSignal will be fired immediately upon interrupt.

initialStdin

If the command expects input on stdin, the input can be supplied as a string with this parameter. This value should not be excessively large, as it is handled as a single string throughout Buildbot – for example, do not pass the contents of a tarball with this parameter.

decodeRC

This is a dictionary that decodes exit codes into results value. For example, {0:SUCCESS,1:FAILURE,2:WARNINGS} will treat the exit code 2 as WARNINGS. The default ({0:SUCCESS}) is to treat just 0 as successful. Any exit code not present in the dictionary will be treated as FAILURE.

2.5.12.20. Shell Sequence

Some steps have a specific purpose, but require multiple shell commands to implement them. For example, a build is often configure; make; make install. We have two ways to handle that:

Create one shell command with all these. To put the logs of each commands in separate logfiles, we need to re-write the script as configure 1> configure_log; ... and to add these configure_log files as logfiles argument of the buildstep. This has the drawback of complicating the shell script, and making it harder to maintain as the logfile name is put in different places.
Create three ShellCommand instances, but this loads the build UI unnecessarily.

ShellSequence is a class that executes not one but a sequence of shell commands during a build. It takes as argument a renderable, or list of commands which are ShellArg objects. Each such object represents a shell invocation.

The single ShellSequence argument aside from the common parameters is:

commands: A list of ShellArg objects or a renderable that returns a list of ShellArg objects.

from buildbot.plugins import steps, util

f.addStep(steps.ShellSequence(
    commands=[
        util.ShellArg(command=['configure']),
        util.ShellArg(command=['make'], logname='make'),
        util.ShellArg(command=['make', 'check_warning'], logname='warning',
                      warnOnFailure=True),
        util.ShellArg(command=['make', 'install'], logname='make install')
    ]))

All these commands share the same configuration of environment, workdir and pty usage that can be set up the same way as in ShellCommand.

class buildbot.steps.shellsequence.ShellArg(self, command=None, logname=None, haltOnFailure=False, flunkOnWarnings=False, flunkOnFailure=False, warnOnWarnings=False, warnOnFailure=False)

Parameters:

command – (see the ShellCommand command argument),
logname – optional log name, used as the stdio log of the command

The haltOnFailure, flunkOnWarnings, flunkOnFailure, warnOnWarnings, warnOnFailure parameters drive the execution of the sequence, the same way steps are scheduled in the build. They have the same default values as for buildsteps - see Parameters Common to all Steps.

Any of the arguments to this class can be renderable.

Note that if logname name does not start with the prefix stdio, that prefix will be set like stdio <logname>. If no logname is supplied, the output of the command will not be collected.

The two ShellSequence methods below tune the behavior of how the list of shell commands are executed, and can be overridden in subclasses.

class buildbot.steps.shellsequence.ShellSequence

shouldRunTheCommand(oneCmd)

Parameters:: oneCmd – a string or a list of strings, as rendered from a ShellArg instance’s command argument.

Determine whether the command oneCmd should be executed. If shouldRunTheCommand returns False, the result of the command will be recorded as SKIPPED. The default method skips all empty strings and empty lists.

getFinalState(): Return the status text of the step in the end. The default value is to set the text describing the execution of the last shell command.

runShellSequence(commands):

Parameters:: commands – list of shell args

This method actually runs the shell sequence. The default run method calls runShellSequence, but subclasses can override run to perform other operations, if desired.

2.5.12.21. Compile

This is meant to handle compiling or building a project written in C. The default command is make all. When the compilation is finished, the log file is scanned for GCC warning messages, a summary log is created with any problems that were seen, and the step is marked as WARNINGS if any were discovered. Through the WarningCountingShellCommand superclass, the number of warnings is stored in a Build Property named warnings-count, which is accumulated over all Compile steps (so if two warnings are found in one step, and three are found in another step, the overall build will have a warnings-count property of 5). Each step can be optionally given a maximum number of warnings via the maxWarnCount parameter. If this limit is exceeded, the step will be marked as a failure.

The default regular expression used to detect a warning is '.*warning[: ].*' , which is fairly liberal and may cause false-positives. To use a different regexp, provide a warningPattern= argument, or use a subclass which sets the warningPattern attribute:

from buildbot.plugins import steps

f.addStep(steps.Compile(command=["make", "test"],
                        warningPattern="^Warning: "))

The warningPattern= can also be a pre-compiled Python regexp object: this makes it possible to add flags like re.I (to use case-insensitive matching).

If warningPattern is set to None then warning counting is disabled.

Note that the compiled warningPattern will have its match method called, which is subtly different from a search. Your regular expression must match the from the beginning of the line. This means that to look for the word “warning” in the middle of a line, you will need to prepend '.*' to your regular expression.

The suppressionFile= argument can be specified as the (relative) path of a file inside the workdir defining warnings to be suppressed from the warning counting and log file. The file will be uploaded to the master from the worker before compiling, and any warning matched by a line in the suppression file will be ignored. This is useful to accept certain warnings (e.g. in some special module of the source tree or in cases where the compiler is being particularly stupid), yet still be able to easily detect and fix the introduction of new warnings.

The file must contain one line per pattern of warnings to ignore. Empty lines and lines beginning with # are ignored. Other lines must consist of a regexp matching the file name, followed by a colon (:), followed by a regexp matching the text of the warning. Optionally this may be followed by another colon and a line number range. For example:

# Sample warning suppression file

mi_packrec.c : .*result of 32-bit shift implicitly converted to 64 bits.* : 560-600
DictTabInfo.cpp : .*invalid access to non-static.*
kernel_types.h : .*only defines private constructors and has no friends.* : 51

If no line number range is specified, the pattern matches the whole file; if only one number is given it matches only on that line.

The suppressionList= argument can be specified as a list of four-tuples as addition or instead of suppressionFile=. The tuple should be [ FILE-RE, WARNING-RE, START, END ]. If FILE-RE is None, then the suppression applies to any file. START and END can be specified as in suppression file, or None.

The default warningPattern regexp only matches the warning text, so line numbers and file names are ignored. To enable line number and file name matching, provide a different regexp and provide a function (callable) as the argument of warningExtractor=. The function is called with three arguments: the BuildStep object, the line in the log file with the warning, and the SRE_Match object of the regexp search for warningPattern. It should return a tuple (filename, linenumber, warning_test). For example:

f.addStep(Compile(command=["make"],
                  warningPattern="^(.\*?):([0-9]+): [Ww]arning: (.\*)$",
                  warningExtractor=Compile.warnExtractFromRegexpGroups,
                  suppressionFile="support-files/compiler_warnings.supp"))

(Compile.warnExtractFromRegexpGroups is a pre-defined function that returns the filename, linenumber, and text from groups (1,2,3) of the regexp match).

In projects with source files in multiple directories, it is possible to get full path names for file names matched in the suppression file, as long as the build command outputs the names of directories as they are entered into and left again. For this, specify regexps for the arguments directoryEnterPattern= and directoryLeavePattern=. The directoryEnterPattern= regexp should return the name of the directory entered into in the first matched group. The defaults, which are suitable for GNU Make, are these:

directoryEnterPattern="make.*: Entering directory [\"`'](.*)['`\"]"
directoryLeavePattern="make.*: Leaving directory"

(TODO: this step needs to be extended to look for GCC error messages as well, and collect them into a separate logfile, along with the source code filenames involved).

2.5.12.22. Configure

class buildbot.steps.shell.Configure

This is intended to handle the ./configure step from autoconf-style projects, or the perl Makefile.PL step from perl MakeMaker.pm-style modules. The default command is ./configure but you can change this by providing a command= parameter. The arguments are identical to ShellCommand.

from buildbot.plugins import steps

f.addStep(steps.Configure())

2.5.12.23. CMake

class buildbot.steps.cmake.CMake

This is intended to handle the cmake step for projects that use CMake-based build systems.

Note

Links below point to the latest CMake documentation. Make sure that you check the documentation for the CMake you use.

In addition to the parameters ShellCommand supports, this step accepts the following parameters:

path: Either a path to a source directory to (re-)generate a build system for it in the current working directory. Or an existing build directory to re-generate its build system.
generator: A build system generator. See cmake-generators(7) for available options.
definitions: A dictionary that contains parameters that will be converted to -D{name}={value} when passed to CMake. A renderable which renders to a dictionary can also be provided, see Properties. Refer to cmake(1) for more information.
options: A list or a tuple that contains options that will be passed to CMake as is. A renderable which renders to a tuple or list can also be provided, see Properties. Refer to cmake(1) for more information.
cmake: Path to the CMake binary. Default is cmake

from buildbot.plugins import steps

...

factory.addStep(
    steps.CMake(
        generator='Ninja',
        definitions={
            'CMAKE_BUILD_TYPE': Property('BUILD_TYPE')
        },
        options=[
            '-Wno-dev'
        ]
    )
)

...

2.5.12.24. Visual C++

These steps are meant to handle compilation using Microsoft compilers. VC++ 6-141 (aka Visual Studio 2003-2015 and VCExpress9) are supported via calling devenv. Msbuild as well as Windows Driver Kit 8 are supported via the MsBuild4, MsBuild12, MsBuild14 and MsBuild141 steps. These steps will take care of setting up a clean compilation environment, parsing the generated output in real time, and delivering as detailed as possible information about the compilation executed.

All of the classes are in buildbot.steps.vstudio. The available classes are:

VC6
VC7
VC8
VC9
VC10
VC11
VC12
VC14
VC141
VS2003
VS2005
VS2008
VS2010
VS2012
VS2013
VS2015
VS2017
VS2019
VS2022
VCExpress9
MsBuild4
MsBuild12
MsBuild14
MsBuild141
MsBuild15
MsBuild16
MsBuild17

The available constructor arguments are

mode: The mode default to rebuild, which means that first all the remaining object files will be cleaned by the compiler. The alternate values are build, where only the updated files will be recompiled, and clean, where the current build files are removed and no compilation occurs.
projectfile: This is a mandatory argument which specifies the project file to be used during the compilation.
config: This argument defaults to release an gives to the compiler the configuration to use.
installdir: This is the place where the compiler is installed. The default value is compiler specific and is the default place where the compiler is installed.
useenv: This boolean parameter, defaulting to False instruct the compiler to use its own settings or the one defined through the environment variables PATH, INCLUDE, and LIB. If any of the INCLUDE or LIB parameter is defined, this parameter automatically switches to True.
PATH: This is a list of path to be added to the PATH environment variable. The default value is the one defined in the compiler options.
INCLUDE: This is a list of path where the compiler will first look for include files. Then comes the default paths defined in the compiler options.
LIB: This is a list of path where the compiler will first look for libraries. Then comes the default path defined in the compiler options.
arch: That one is only available with the class VS2005 (VC8). It gives the target architecture of the built artifact. It defaults to x86 and does not apply to MsBuild4 or MsBuild12. Please see platform below.
project: This gives the specific project to build from within a workspace. It defaults to building all projects. This is useful for building cmake generate projects.
platform: This is a mandatory argument for MsBuild4 and MsBuild12 specifying the target platform such as ‘Win32’, ‘x64’ or ‘Vista Debug’. The last one is an example of driver targets that appear once Windows Driver Kit 8 is installed.
defines: That one is only available with the MsBuild family of classes. It allows to define pre-processor constants used by the compiler.

Here is an example on how to drive compilation with Visual Studio 2013:

from buildbot.plugins import steps

f.addStep(
    steps.VS2013(projectfile="project.sln", config="release",
        arch="x64", mode="build",
           INCLUDE=[r'C:\3rd-party\libmagic\include'],
           LIB=[r'C:\3rd-party\libmagic\lib-x64']))

Here is a similar example using “MsBuild12”:

from buildbot.plugins import steps

# Build one project in Release mode for Win32
f.addStep(
    steps.MsBuild12(projectfile="trunk.sln", config="Release", platform="Win32",
            workdir="trunk",
            project="tools\\protoc"))

# Build the entire solution in Debug mode for x64
f.addStep(
    steps.MsBuild12(projectfile="trunk.sln", config='Debug', platform='x64',
            workdir="trunk"))

2.5.12.25. Cppcheck

This step runs cppcheck, analyse its output, and set the outcome in Properties.

from buildbot.plugins import steps

f.addStep(steps.Cppcheck(enable=['all'], inconclusive=True]))

This class adds the following arguments:

binary: (Optional, defaults to cppcheck) Use this if you need to give the full path to the cppcheck binary or if your binary is called differently.
source: (Optional, defaults to ['.']) This is the list of paths for the sources to be checked by this step.
enable: (Optional) Use this to give a list of the message classes that should be in cppcheck report. See the cppcheck man page for more information.
inconclusive: (Optional) Set this to True if you want cppcheck to also report inconclusive results. See the cppcheck man page for more information.
extra_args: (Optional) This is the list of extra arguments to be given to the cppcheck command.

All other arguments are identical to ShellCommand.

2.5.12.26. Robocopy

class buildbot.steps.mswin.Robocopy

This step runs robocopy on Windows.

Robocopy is available in versions of Windows starting with Windows Vista and Windows Server 2008. For previous versions of Windows, it’s available as part of the Windows Server 2003 Resource Kit Tools.

from buildbot.plugins import steps, util

f.addStep(
    steps.Robocopy(
        name='deploy_binaries',
        description='Deploying binaries...',
        descriptionDone='Deployed binaries.',
        source=util.Interpolate('Build\\Bin\\%(prop:configuration)s'),
        destination=util.Interpolate('%(prop:deploy_dir)\\Bin\\%(prop:configuration)s'),
        mirror=True
    )
)

Available constructor arguments are:

source: The path to the source directory (mandatory).
destination: The path to the destination directory (mandatory).
files: An array of file names or patterns to copy.
recursive: Copy files and directories recursively (/E parameter).
mirror: Mirror the source directory in the destination directory, including removing files that don’t exist anymore (/MIR parameter).
move: Delete the source directory after the copy is complete (/MOVE parameter).
exclude_files: An array of file names or patterns to exclude from the copy (/XF parameter).
exclude_dirs: An array of directory names or patterns to exclude from the copy (/XD parameter).
custom_opts: An array of custom parameters to pass directly to the robocopy command.
verbose: Whether to output verbose information (/V /TS /FP parameters).

Note that parameters /TEE /NP will always be appended to the command to signify, respectively, to output logging to the console, use Unicode logging, and not print any percentage progress information for each file.

2.5.12.27. Test

from buildbot.plugins import steps

f.addStep(steps.Test())

This is meant to handle unit tests. The default command is make test, and the warnOnFailure flag is set. The other arguments are identical to ShellCommand.

2.5.12.28. TreeSize

from buildbot.plugins import steps

f.addStep(steps.TreeSize())

This is a simple command that uses the du tool to measure the size of the code tree. It puts the size (as a count of 1024-byte blocks, aka ‘KiB’ or ‘kibibytes’) on the step’s status text, and sets a build property named tree-size-KiB with the same value. All arguments are identical to ShellCommand.

2.5.12.29. PerlModuleTest

from buildbot.plugins import steps

f.addStep(steps.PerlModuleTest())

This is a simple command that knows how to run tests of perl modules. It parses the output to determine the number of tests passed and failed and total number executed, saving the results for later query. The command is prove --lib lib -r t, although this can be overridden with the command argument. All other arguments are identical to those for ShellCommand.

2.5.12.30. SubunitShellCommand

class buildbot.steps.subunit.SubunitShellCommand

This buildstep is similar to ShellCommand, except that it runs the log content through a subunit filter to extract test and failure counts.

from buildbot.plugins import steps

f.addStep(steps.SubunitShellCommand(command="make test"))

This runs make test and filters it through subunit. The ‘tests’ and ‘test failed’ progress metrics will now accumulate test data from the test run.

If failureOnNoTests is True, this step will fail if no test is run. By default failureOnNoTests is False.

2.5.12.31. HLint

The HLint step runs Twisted Lore, a lint-like checker over a set of .xhtml files. Any deviations from recommended style is flagged and put in the output log.

The step looks at the list of changes in the build to determine which files to check - it does not check all files. It specifically excludes any .xhtml files in the top-level sandbox/ directory.

The step takes a single, optional, parameter: python. This specifies the Python executable to use to run Lore.

from buildbot.plugins import steps

f.addStep(steps.HLint())

2.5.12.32. MaxQ

MaxQ (http://maxq.tigris.org/) is a web testing tool that allows you to record HTTP sessions and play them back. The MaxQ step runs this framework.

from buildbot.plugins import steps

f.addStep(steps.MaxQ(testdir='tests/'))

The single argument, testdir, specifies where the tests should be run. This directory will be passed to the run_maxq.py command, and the results analyzed.

2.5.12.33. Trigger

class buildbot.steps.trigger.Trigger

The counterpart to the Triggerable scheduler is the Trigger build step:

from buildbot.plugins import steps

f.addStep(steps.Trigger(schedulerNames=['build-prep'],
                        waitForFinish=True,
                        updateSourceStamp=True,
                        set_properties={ 'quick' : False }))

The SourceStamps to use for the triggered build are controlled by the arguments updateSourceStamp, alwaysUseLatest, and sourceStamps.

Hyperlinks are added to the build detail web pages for each triggered build.

schedulerNames

Lists the Triggerable schedulers that should be triggered when this step is executed.

Note

It is possible, but not advisable, to create a cycle where a build continually triggers itself, because the schedulers are specified by name.

unimportantSchedulerNames

When waitForFinish is True, all schedulers in this list will not cause the trigger step to fail. unimportantSchedulerNames must be a subset of schedulerNames. If waitForFinish is False, unimportantSchedulerNames will simply be ignored.

waitForFinish

If True, the step will not finish until all of the builds from the triggered schedulers have finished.

If False (the default) or not given, then the buildstep succeeds immediately after triggering the schedulers.

updateSourceStamp

If True (the default), then the step updates the source stamps given to the Triggerable schedulers to include got_revision (the revision actually used in this build) as revision (the revision to use in the triggered builds). This is useful to ensure that all of the builds use exactly the same source stamps, even if other Changes have occurred while the build was running.

If False (and neither of the other arguments are specified), then the exact same SourceStamps are used.

alwaysUseLatest

If True, then no SourceStamps are given, corresponding to using the latest revisions of the repositories specified in the Source steps. This is useful if the triggered builds use to a different source repository.

sourceStamps

Accepts a list of dictionaries containing the keys branch, revision, repository, project, and optionally patch_level, patch_body, patch_subdir, patch_author and patch_comment and creates the corresponding SourceStamps. If only one sourceStamp has to be specified then the argument sourceStamp can be used for a dictionary containing the keys mentioned above. The arguments updateSourceStamp, alwaysUseLatest, and sourceStamp can be specified using properties.

set_properties

Allows control of the properties that are passed to the triggered scheduler. The parameter takes a dictionary mapping property names to values. You may use Interpolate here to dynamically construct new property values. For the simple case of copying a property, this might look like:

set_properties={"my_prop1" : Property("my_prop1"),
                "my_prop2" : Property("my_prop2")}

where Property is an instance of buildbot.process.properties.Property.

Note

The copy_properties parameter, given a list of properties to copy into the new build request, has been deprecated in favor of explicit use of set_properties.

Dynamic Trigger

Sometimes it is desirable to select which scheduler to trigger, and which properties to set dynamically, at the time of the build. For this purpose, the Trigger step supports a method that you can customize in order to override statically defined schedulernames, set_properties and optionally unimportant.

getSchedulersAndProperties()

Returns:: list of dictionaries containing the keys ‘sched_name’, ‘props_to_set’ and ‘unimportant’ optionally via deferred.

This method returns a list of dictionaries describing what scheduler to trigger, with which properties and if the scheduler is unimportant. The properties should already be rendered (ie, concrete value, not objects wrapped by Interpolate or Property). Since this function happens at build-time, the property values are available from the step and can be used to decide what schedulers or properties to use.

With this method, you can also trigger the same scheduler multiple times with different set of properties. The sourcestamp configuration is however the same for each triggered build request.

2.5.12.34. BuildEPYDoc

class buildbot.steps.python.BuildEPYDoc

epydoc is a tool for generating API documentation for Python modules from their docstrings. It reads all the .py files from your source tree, processes the docstrings therein, and creates a large tree of .html files (or a single .pdf file).

The BuildEPYDoc step will run epydoc to produce this API documentation, and will count the errors and warnings from its output.

You must supply the command line to be used. The default is make epydocs, which assumes that your project has a Makefile with an epydocs target. You might wish to use something like epydoc -o apiref source/PKGNAME instead. You might also want to add option –pdf to generate a PDF file instead of a large tree of HTML files.

The API docs are generated in-place in the build tree (under the workdir, in the subdirectory controlled by the option -o argument). To make them useful, you will probably have to copy them to somewhere they can be read. For example if you have server with configured nginx web server, you can place generated docs to it’s public folder with command like rsync -ad apiref/ dev.example.com:~/usr/share/nginx/www/current-apiref/. You might instead want to bundle them into a tarball and publish it in the same place where the generated install tarball is placed.

from buildbot.plugins import steps

f.addStep(steps.BuildEPYDoc(command=["epydoc", "-o", "apiref", "source/mypkg"]))

2.5.12.35. PyFlakes

class buildbot.steps.python.PyFlakes

PyFlakes is a tool to perform basic static analysis of Python code to look for simple errors, like missing imports and references of undefined names. It is like a fast and simple form of the C lint program. Other tools (like pychecker) provide more detailed results but take longer to run.

The PyFlakes step will run pyflakes and count the various kinds of errors and warnings it detects.

You must supply the command line to be used. The default is make pyflakes, which assumes you have a top-level Makefile with a pyflakes target. You might want to use something like pyflakes . or pyflakes src.

from buildbot.plugins import steps

f.addStep(steps.PyFlakes(command=["pyflakes", "src"]))

2.5.12.36. Sphinx

class buildbot.steps.python.Sphinx

Sphinx is the Python Documentation Generator. It uses RestructuredText as input format.

The Sphinx step will run sphinx-build or any other program specified in its sphinx argument and count the various warnings and error it detects.

from buildbot.plugins import steps

f.addStep(steps.Sphinx(sphinx_builddir="_build"))

This step takes the following arguments:

sphinx_builddir: (required) Name of the directory where the documentation will be generated.
sphinx_sourcedir: (optional, defaulting to .), Name the directory where the conf.py file will be found
sphinx_builder: (optional) Indicates the builder to use.
sphinx: (optional, defaulting to sphinx-build) Indicates the executable to run.
tags: (optional) List of tags to pass to sphinx-build
defines: (optional) Dictionary of defines to overwrite values of the conf.py file.
strict_warnings: (optional) Boolean, defaults to False. Treat all warnings as errors.
mode: (optional) String, one of full or incremental (the default). If set to full, indicates to Sphinx to rebuild everything without re-using the previous build results.

2.5.12.37. PyLint

Similarly, the PyLint step will run pylint and analyze the results.

You must supply the command line to be used. There is no default.

from buildbot.plugins import steps

f.addStep(steps.PyLint(command=["pylint", "src"]))

This step takes the following arguments:

store_results: (Optional, defaults to True) If True, the test results will be stored in the test database.

2.5.12.38. Trial

class buildbot.steps.python_twisted.Trial

This step runs a unit test suite using trial, a unittest-like testing framework that is a component of Twisted Python.

The Trial takes the following arguments:

python: (string or list of strings, optional) Which python executable to use. Will form the start of the argv array that will launch trial. If you use this, you should set trial to an explicit path (like /usr/bin/trial or ./bin/trial). Defaults to None, which leaves it out entirely (running ‘trial args’ instead of python ./bin/trial args’). Likely values are 'python', ['python3.5'], ['python', '-Wall'], etc.
trial: (string, optional) Which ‘trial’ executable to run Defaults to 'trial', which will cause $PATH to be searched and probably find /usr/bin/trial. If you set python, this should be set to an explicit path (because python3.5 trial will not work).
trialMode: (list of strings, optional) A list of arguments to pass to trial to set the reporting mode. This defaults to ['-to'] which means ‘verbose colorless output’ to the trial that comes with Twisted-2.0.x and at least -2.1.0 . Newer versions of Twisted may come with a trial that prefers ['--reporter=bwverbose'].
trialArgs: (list of strings, optional) A list of arguments to pass to trial. This can be used to turn on any extra flags you like. Defaults to [].
jobs: (integer, optional) Defines the number of parallel jobs.
tests: (list of strings, optional) Defines the test modules to run. For example, ['twisted.test.test_defer', 'twisted.test.test_process'] If this is a string, it will be converted into a one-item list.
testChanges: (boolean, optional) Selects the tests according to the changes in the Build. If set, this will override the tests parameter and asks the Build for all the files that make up the Changes going into this build. The filenames will be passed to trial asking to run just the tests necessary to cover the changes.
recurse: (boolean, optional) Selects the --recurse option of trial. This allows test cases to be found in deeper subdirectories of the modules listed in tests. When using testChanges this option is not necessary.
reactor: (boolean, optional) Selects the reactor to use within Trial. For example, options are gtk or java. If not provided, the Twisted’s usual platform-dependent default is used.
randomly: (boolean, optional) If True, adds the --random=0 argument, which instructs trial to run the unit tests in a random order each time. This occasionally catches problems that might be masked when one module always runs before another.
**kwargs: (dict, optional) The step inherits all arguments of ShellMixin except command.

Trial creates and switches into a directory named _trial_temp/ before running the tests, and sends the twisted log (which includes all exceptions) to a file named test.log. This file will be pulled up to the master where it can be seen as part of the status output.

from buildbot.plugins import steps

f.addStep(steps.Trial(tests='petmail.test'))

2.5.12.39. RemovePYCs

class buildbot.steps.python_twisted.RemovePYCs

This is a simple built-in step that will remove .pyc files from the workdir. This is useful in builds that update their source (and thus do not automatically delete .pyc files) but where some part of the build process is dynamically searching for Python modules. Notably, trial has a bad habit of finding old test modules.

from buildbot.plugins import steps

f.addStep(steps.RemovePYCs())

2.5.12.40. HTTP Requests

Using the HTTPStep step, it is possible to perform HTTP requests in order to trigger another REST service about the progress of the build.

Note

This step requires the txrequests and requests Python libraries.

The parameters are the following:

url: (mandatory) The URL where to send the request
method: The HTTP method to use (out of POST, GET, PUT, DELETE, HEAD or OPTIONS), default to POST.
params: Dictionary of URL parameters to append to the URL.
data: The body to attach the request. If a dictionary is provided, form-encoding will take place.
headers: Dictionary of headers to send.
hide_request_headers: Iterable of request headers to be hidden from the log. The header will be listed in the log but the value will be shown as <HIDDEN>.
hide_response_headers: Iterable of response headers to be hidden from the log. The header will be listed in the log but the value will be shown as <HIDDEN>.
other params: Any other keywords supported by the requests api can be passed to this step.

Note

The entire Buildbot master process shares a single Requests Session object. This has the advantage of supporting connection re-use and other HTTP/1.1 features. However, it also means that any cookies or other state changed by one step will be visible to other steps, causing unexpected results. This behavior may change in future versions.

When the method is known in advance, class with the name of the method can also be used. In this case, it is not necessary to specify the method.

Example:

from buildbot.plugins import steps, util

f.addStep(steps.POST('http://myRESTService.example.com/builds',
                     data = {
                        'builder': util.Property('buildername'),
                        'buildnumber': util.Property('buildnumber'),
                        'workername': util.Property('workername'),
                        'revision': util.Property('got_revision')
                     }))

2.5.12.41. Worker Filesystem Steps

Here are some buildsteps for manipulating the worker’s filesystem.

FileExists

This step will assert that a given file exists, failing if it does not. The filename can be specified with a property.

from buildbot.plugins import steps

f.addStep(steps.FileExists(file='test_data'))

This step requires worker version 0.8.4 or later.

CopyDirectory

This command copies a directory on the worker.

from buildbot.plugins import steps

f.addStep(steps.CopyDirectory(src="build/data", dest="tmp/data"))

This step requires worker version 0.8.5 or later.

The CopyDirectory step takes the following arguments:

timeout: If the copy command fails to produce any output for this many seconds, it is assumed to be locked up and will be killed. This defaults to 120 seconds. Pass None to disable.
maxTime: If the command takes longer than this many seconds, it will be killed. This is disabled by default.

RemoveDirectory

This command recursively deletes a directory on the worker.

from buildbot.plugins import steps

f.addStep(steps.RemoveDirectory(dir="build/build"))

This step requires worker version 0.8.4 or later.

MakeDirectory

This command creates a directory on the worker.

from buildbot.plugins import steps

f.addStep(steps.MakeDirectory(dir="build/build"))

This step requires worker version 0.8.5 or later.

2.5.12.42. Transferring Files

class buildbot.steps.transfer.FileUpload

class buildbot.steps.transfer.FileDownload

Most of the work involved in a build will take place on the worker. But occasionally it is useful to do some work on the buildmaster side. The most basic way to involve the buildmaster is simply to move a file from the worker to the master, or vice versa. There are a pair of steps named FileUpload and FileDownload to provide this functionality. FileUpload moves a file up to the master, while FileDownload moves a file down from the master.

As an example, let’s assume that there is a step which produces an HTML file within the source tree that contains some sort of generated project documentation. And let’s assume that we run nginx web server on the buildmaster host for serving static files. We want to move this file to the buildmaster, into a /usr/share/nginx/www/ directory, so it can be visible to developers. This file will wind up in the worker-side working directory under the name docs/reference.html. We want to put it into the master-side /usr/share/nginx/www/ref.html, and add a link to the HTML status to the uploaded file.

from buildbot.plugins import steps

f.addStep(steps.ShellCommand(command=["make", "docs"]))
f.addStep(steps.FileUpload(workersrc="docs/reference.html",
                           masterdest="/usr/share/nginx/www/ref.html",
                           url="http://somesite/~buildbot/ref.html"))

The masterdest= argument will be passed to os.path.expanduser, so things like ~ will be expanded properly. Non-absolute paths will be interpreted relative to the buildmaster’s base directory. Likewise, the workersrc= argument will be expanded and interpreted relative to the builder’s working directory.

Note

The copied file will have the same permissions on the master as on the worker, look at the mode= parameter to set it differently.

To move a file from the master to the worker, use the FileDownload command. For example, let’s assume that some step requires a configuration file that, for whatever reason, could not be recorded in the source code repository or generated on the worker side:

from buildbot.plugins import steps

f.addStep(steps.FileDownload(mastersrc="~/todays_build_config.txt",
                             workerdest="build_config.txt"))
f.addStep(steps.ShellCommand(command=["make", "config"]))

Like FileUpload, the mastersrc= argument is interpreted relative to the buildmaster’s base directory, and the workerdest= argument is relative to the builder’s working directory. If the worker is running in ~worker, and the builder’s builddir is something like tests-i386, then the workdir is going to be ~worker/tests-i386/build, and a workerdest= of foo/bar.html will get put in ~worker/tests-i386/build/foo/bar.html. Both of these commands will create any missing intervening directories.

Other Parameters

The maxsize= argument lets you set a maximum size for the file to be transferred. This may help to avoid surprises: transferring a 100MB coredump when you were expecting to move a 10kB status file might take an awfully long time. The blocksize= argument controls how the file is sent over the network: larger blocksizes are slightly more efficient but also consume more memory on each end, and there is a hard-coded limit of about 640kB.

The mode= argument allows you to control the access permissions of the target file, traditionally expressed as an octal integer. The most common value is probably 0o755, which sets the x executable bit on the file (useful for shell scripts and the like). The default value for mode= is None, which means the permission bits will default to whatever the umask of the writing process is. The default umask tends to be fairly restrictive, but at least on the worker you can make it less restrictive with a --umask command-line option at creation time (Worker Options).

The keepstamp= argument is a boolean that, when True, forces the modified and accessed time of the destination file to match the times of the source file. When False (the default), the modified and accessed times of the destination file are set to the current time on the buildmaster.

The url= argument allows you to specify an url that will be displayed in the HTML status. The title of the url will be the name of the item transferred (directory for DirectoryUpload or file for FileUpload). This allows the user to add a link to the uploaded item if that one is uploaded to an accessible place.

For FileUpload, the urlText= argument allows you to specify the url title that will be displayed in the web UI.

Transferring Directories

class buildbot.steps.transfer.DirectoryUpload

To transfer complete directories from the worker to the master, there is a BuildStep named DirectoryUpload. It works like FileUpload, just for directories. However it does not support the maxsize, blocksize and mode arguments. As an example, let’s assume an generated project documentation, which consists of many files (like the output of doxygen or epydoc). And let’s assume that we run nginx web server on buildmaster host for serving static files. We want to move the entire documentation to the buildmaster, into a /usr/share/nginx/www/docs directory, and add a link to the uploaded documentation on the HTML status page. On the worker-side the directory can be found under docs:

from buildbot.plugins import steps

f.addStep(steps.ShellCommand(command=["make", "docs"]))
f.addStep(steps.DirectoryUpload(workersrc="docs",
                                masterdest="/usr/share/nginx/www/docs",
                                url="~buildbot/docs"))

The DirectoryUpload step will create all necessary directories and transfers empty directories, too.

The maxsize and blocksize parameters are the same as for FileUpload, although note that the size of the transferred data is implementation-dependent, and probably much larger than you expect due to the encoding used (currently tar).

The optional compress argument can be given as 'gz' or 'bz2' to compress the datastream.

For DirectoryUpload the urlText= argument allows you to specify the url title that will be displayed in the web UI.

Note

The permissions on the copied files will be the same on the master as originally on the worker, see option buildbot-worker create-worker --umask to change the default one.

Transferring Multiple Files At Once

class buildbot.steps.transfer.MultipleFileUpload

In addition to the FileUpload and DirectoryUpload steps there is the MultipleFileUpload step for uploading a bunch of files (and directories) in a single BuildStep. The step supports all arguments that are supported by FileUpload and DirectoryUpload, but instead of a the single workersrc parameter it takes a (plural) workersrcs parameter. This parameter should either be a list, something that can be rendered as a list or a string which will be converted to a list. Additionally it supports the glob parameter if this parameter is set to True all arguments in workersrcs will be parsed through glob and the results will be uploaded to masterdest.:

from buildbot.plugins import steps

f.addStep(steps.ShellCommand(command=["make", "test"]))
f.addStep(steps.ShellCommand(command=["make", "docs"]))
f.addStep(steps.MultipleFileUpload(workersrcs=["docs", "test-results.html"],
                                   masterdest="/usr/share/nginx/www/",
                                   url="~buildbot"))

The url= parameter, can be used to specify a link to be displayed in the HTML status of the step.

The way URLs are added to the step can be customized by extending the MultipleFileUpload class. The allUploadsDone method is called after all files have been uploaded and sets the URL. The uploadDone method is called once for each uploaded file and can be used to create file-specific links.

import os

from buildbot.plugins import steps

class CustomFileUpload(steps.MultipleFileUpload):
    linkTypes = ('.html', '.txt')

    def linkFile(self, basename):
        name, ext = os.path.splitext(basename)
        return ext in self.linkTypes

    def uploadDone(self, result, source, masterdest):
        if self.url:
            basename = os.path.basename(source)
            if self.linkFile(basename):
                self.addURL(self.url + '/' + basename, basename)

    def allUploadsDone(self, result, sources, masterdest):
        if self.url:
            notLinked = [src for src in sources if not self.linkFile(src)]
            numFiles = len(notLinked)
            if numFiles:
                self.addURL(self.url, '... %d more' % numFiles)

For MultipleFileUpload the urlText= argument allows you to specify the url title that will be displayed in the web UI.

2.5.12.43. Transferring Strings

class buildbot.steps.transfer.StringDownload

class buildbot.steps.transfer.JSONStringDownload

class buildbot.steps.transfer.JSONPropertiesDownload

Sometimes it is useful to transfer a calculated value from the master to the worker. Instead of having to create a temporary file and then use FileDownload, you can use one of the string download steps.

from buildbot.plugins import steps, util

f.addStep(steps.StringDownload(util.Interpolate("%(src::branch)s-%(prop:got_revision)s\n"),
        workerdest="buildid.txt"))

StringDownload works just like FileDownload except it takes a single argument, s, representing the string to download instead of a mastersrc argument.

from buildbot.plugins import steps

buildinfo = {
    'branch': Property('branch'),
    'got_revision': Property('got_revision')
}
f.addStep(steps.JSONStringDownload(buildinfo, workerdest="buildinfo.json"))

JSONStringDownload is similar, except it takes an o argument, which must be JSON serializable, and transfers that as a JSON-encoded string to the worker.

from buildbot.plugins import steps

f.addStep(steps.JSONPropertiesDownload(workerdest="build-properties.json"))

JSONPropertiesDownload transfers a json-encoded string that represents a dictionary where properties maps to a dictionary of build property name to property value; and sourcestamp represents the build’s sourcestamp.

2.5.12.44. MasterShellCommand

class buildbot.steps.master.MasterShellCommand

Occasionally, it is useful to execute some task on the master, for example to create a directory, deploy a build result, or trigger some other centralized processing. This is possible, in a limited fashion, with the MasterShellCommand step.

This step operates similarly to a regular ShellCommand, but executes on the master, instead of the worker. To be clear, the enclosing Build object must still have a worker object, just as for any other step – only, in this step, the worker does not do anything.

In the following example, the step renames a tarball based on the day of the week.

from buildbot.plugins import steps

f.addStep(steps.FileUpload(workersrc="widgetsoft.tar.gz",
                     masterdest="/var/buildoutputs/widgetsoft-new.tar.gz"))
f.addStep(steps.MasterShellCommand(
    command="mv widgetsoft-new.tar.gz widgetsoft-`date +%a`.tar.gz",
    workdir="/var/buildoutputs"))

Note

By default, this step passes a copy of the buildmaster’s environment variables to the subprocess. To pass an explicit environment instead, add an env={..} argument.

Environment variables constructed using the env argument support expansion so that if you just want to prepend /home/buildbot/bin to the PATH environment variable, you can do it by putting the value ${PATH} at the end of the value like in the example below. Variables that don’t exist on the master will be replaced by "".

from buildbot.plugins import steps

f.addStep(steps.MasterShellCommand(
              command=["make", "www"],
              env={'PATH': ["/home/buildbot/bin",
                            "${PATH}"]}))

Note that environment values must be strings (or lists that are turned into strings). In particular, numeric properties such as buildnumber must be substituted using Interpolate.

workdir: (optional) The directory from which the command will be run.
interruptSignal: (optional) Signal to use to end the process if the step is interrupted.

2.5.12.45. LogRenderable

class buildbot.steps.master.LogRenderable

This build step takes content which can be renderable and logs it in a pretty-printed format. It can be useful for debugging properties during a build.

2.5.12.46. Assert

class buildbot.steps.master.Assert

This build step takes a Renderable or constant passed in as first argument. It will test if the expression evaluates to True and succeed the step or fail the step otherwise.

2.5.12.47. SetProperty

class buildbot.steps.master.SetProperty

SetProperty takes two arguments of property and value where the value is to be assigned to the property key. It is usually called with the value argument being specified as an Interpolate object which allows the value to be built from other property values:

from buildbot.plugins import steps, util

f.addStep(
    steps.SetProperty(
        property="SomeProperty",
        value=util.Interpolate("sch=%(prop:scheduler)s, worker=%(prop:workername)s")
    )
)

2.5.12.48. SetProperties

class buildbot.steps.master.SetProperties

SetProperties takes a dictionary to be turned into build properties.

It is similar to SetProperty, and meant to be used with a Renderer function or a dictionary of Interpolate objects which allows the value to be built from other property values:

"""Example borrowed from Julia's master.cfg
   https://github.com/staticfloat/julia-buildbot (MIT)"""
from buildbot.plugins import *

@util.renderer
def compute_artifact_filename(props):
    # Get the output of the `make print-BINARYDIST_FILENAME` step
    reported_filename = props.getProperty('artifact_filename')

    # First, see if we got a BINARYDIST_FILENAME output
    if reported_filename[:26] == "BINARYDIST_FILENAME=":
        local_filename = util.Interpolate(reported_filename[26:].strip() +
                                          "%(prop:os_pkg_ext)s")
    else:
        # If not, use non-sf/consistent_distnames naming
        if is_mac(props):
            template = \
                "path/to/Julia-%(prop:version)s-%(prop:shortcommit)s.%(prop:os_pkg_ext)s"
        elif is_winnt(props):
            template = \
                "julia-%(prop:version)s-%(prop:tar_arch)s.%(prop:os_pkg_ext)s"
        else:
            template = \
                "julia-%(prop:shortcommit)s-Linux-%(prop:tar_arch)s.%(prop:os_pkg_ext)s"

        local_filename = util.Interpolate(template)

    # upload_filename always follows sf/consistent_distname rules
    upload_filename = util.Interpolate(
        "julia-%(prop:shortcommit)s-%(prop:os_name)s%(prop:bits)s.%(prop:os_pkg_ext)s")

    return {
        "local_filename": local_filename
        "upload_filename": upload_filename
    }

f1.addStep(steps.SetProperties(properties=compute_artifact_filename))

2.5.12.49. SetPropertyFromCommand

class buildbot.steps.shell.SetPropertyFromCommand

This buildstep is similar to ShellCommand, except that it captures the output of the command into a property. It is usually used like this:

from buildbot.plugins import steps

f.addStep(steps.SetPropertyFromCommand(command="uname -a", property="uname"))

This runs uname -a and captures its stdout, stripped of leading and trailing whitespace, in the property uname. To avoid stripping, add strip=False.

The property argument can be specified as an Interpolate object, allowing the property name to be built from other property values.

Passing includeStdout=False (defaults to True) stops capture from stdout.

Passing includeStderr=True (defaults to False) allows capture from stderr.

The more advanced usage allows you to specify a function to extract properties from the command output. Here you can use regular expressions, string interpolation, or whatever you would like. In this form, extract_fn should be passed, and not Property. The extract_fn function is called with three arguments: the exit status of the command, its standard output as a string, and its standard error as a string. It should return a dictionary containing all new properties.

Note that passing in extract_fn will set includeStderr to True.

def glob2list(rc, stdout, stderr):
    jpgs = [l.strip() for l in stdout.split('\n')]
    return {'jpgs': jpgs}

f.addStep(SetPropertyFromCommand(command="ls -1 *.jpg", extract_fn=glob2list))

Note that any ordering relationship of the contents of stdout and stderr is lost. For example, given:

f.addStep(SetPropertyFromCommand(
    command="echo output1; echo error >&2; echo output2",
    extract_fn=my_extract))

Then my_extract will see stdout="output1\noutput2\n" and stderr="error\n".

Avoid using the extract_fn form of this step with commands that produce a great deal of output, as the output is buffered in memory until complete.

class buildbot.steps.worker.SetPropertiesFromEnv

2.5.12.50. SetPropertiesFromEnv

Buildbot workers (later than version 0.8.3) provide their environment variables to the master on connect. These can be copied into Buildbot properties with the SetPropertiesFromEnv step. Pass a variable or list of variables in the variables parameter, then simply use the values as properties in a later step.

Note that on Windows, environment variables are case-insensitive, but Buildbot property names are case sensitive. The property will have exactly the variable name you specify, even if the underlying environment variable is capitalized differently. If, for example, you use variables=['Tmp'], the result will be a property named Tmp, even though the environment variable is displayed as TMP in the Windows GUI.

from buildbot.plugins import steps, util

f.addStep(steps.SetPropertiesFromEnv(variables=["SOME_JAVA_LIB_HOME", "JAVAC"]))
f.addStep(steps.Compile(commands=[util.Interpolate("%(prop:JAVAC)s"),
                                  "-cp",
                                  util.Interpolate("%(prop:SOME_JAVA_LIB_HOME)s")]))

Note that this step requires that the worker be at least version 0.8.3. For previous versions, no environment variables are available (the worker environment will appear to be empty).

2.5.12.51. RpmBuild

The RpmBuild step builds RPMs based on a spec file:

from buildbot.plugins import steps

f.addStep(steps.RpmBuild(specfile="proj.spec", dist='.el5'))

The step takes the following parameters

specfile: The .spec file to build from
topdir: Definition for _topdir, defaulting to the workdir.
builddir: Definition for _builddir, defaulting to the workdir.
rpmdir: Definition for _rpmdir, defaulting to the workdir.
sourcedir: Definition for _sourcedir, defaulting to the workdir.
srcrpmdir: Definition for _srcrpmdir, defaulting to the workdir.
dist: Distribution to build, used as the definition for _dist.
define: A dictionary of additional definitions to declare.
autoRelease: If true, use the auto-release mechanics.
vcsRevision: If true, use the version-control revision mechanics. This uses the got_revision property to determine the revision and define _revision. Note that this will not work with multi-codebase builds.

2.5.12.52. RpmLint

The RpmLint step checks for common problems in RPM packages or spec files:

from buildbot.plugins import steps

f.addStep(steps.RpmLint())

The step takes the following parameters

fileloc: The file or directory to check. In case of a directory, it is recursively searched for RPMs and spec files to check.
config: Path to a rpmlint config file. This is passed as the user configuration file if present.

2.5.12.53. MockBuildSRPM Step

The MockBuildSRPM step builds a SourceRPM based on a spec file and optionally a source directory:

Mock (http://fedoraproject.org/wiki/Projects/Mock) creates chroots and builds packages in them. It populates the changeroot with a basic system and the packages listed as build requirement. The type of chroot to build is specified with the root parameter. To use mock your Buildbot user must be added to the mock group.

from buildbot.plugins import steps

f.addStep(steps.MockBuildSRPM(root='default', spec='mypkg.spec'))

The step takes the following parameters

root: Use chroot configuration defined in /etc/mock/<root>.cfg.
resultdir: The directory where the logfiles and the SourceRPM are written to.
spec: Build the SourceRPM from this spec file.
sources: Path to the directory containing the sources, defaulting to ..

Note

It is necessary to pass the resultdir parameter to let the master watch for (and display) changes to build.log, root.log, and state.log.

2.5.12.54. MockRebuild

The MockRebuild step rebuilds a SourceRPM package:

from buildbot.plugins import steps

f.addStep(steps.MockRebuild(root='default', srpm='mypkg-1.0-1.src.rpm'))

The step takes the following parameters

root: Uses chroot configuration defined in /etc/mock/<root>.cfg.
resultdir: The directory where the logfiles and the SourceRPM are written to.
srpm: The path to the SourceRPM to rebuild.

Note

It is necessary to pass the resultdir parameter to let the master watch for (and display) changes to build.log, root.log, and state.log.

2.5.12.55. DebPbuilder

The DebPbuilder step builds Debian packages within a chroot built by pbuilder. It populates the chroot with a basic system and the packages listed as build requirements. The type of the chroot to build is specified with the distribution, distribution and mirror parameter. To use pbuilder, your Buildbot user must have the right to run pbuilder as root using sudo.

from buildbot.plugins import steps

f.addStep(steps.DebPbuilder())

The step takes the following parameters

architecture: Architecture to build chroot for.
distribution: Name, or nickname, of the distribution. Defaults to ‘stable’.
basetgz: Path of the basetgz to use for building.
mirror: URL of the mirror used to download the packages from.
othermirror: List of additional deb URL ... lines to add to sources.list.
extrapackages: List if packages to install in addition to the base system.
keyring: Path to a gpg keyring to verify the downloaded packages. This is necessary if you build for a foreign distribution.
components: Repos to activate for chroot building.

2.5.12.56. DebCowbuilder

The DebCowbuilder step is a subclass of DebPbuilder, which use cowbuilder instead of pbuilder.

2.5.12.57. DebLintian

The DebLintian step checks a build .deb for bugs and policy violations. The packages or changes file to test is specified in fileloc.

from buildbot.plugins import steps, util

f.addStep(steps.DebLintian(fileloc=util.Interpolate("%(prop:deb-changes)s")))

This class adds the following arguments:

fileloc: (Optional, string) Location of the .deb or .changes files to test.
suppressTags: (Optional, list of strings) List of tags to suppress.

All other arguments are identical to ShellCommand.

BuildSteps are usually specified in the buildmaster’s configuration file, in a list that given to a BuildFactory. The BuildStep instances in this list are used as templates to construct new independent copies for each build (so that state can be kept on the BuildStep in one build without affecting a later build). Each BuildFactory can be created with a list of steps, or the factory can be created empty and then steps added to it using the addStep method:

from buildbot.plugins import util, steps

f = util.BuildFactory()
f.addSteps([
    steps.SVN(repourl="http://svn.example.org/Trunk/"),
    steps.ShellCommand(command=["make", "all"]),
    steps.ShellCommand(command=["make", "test"])
])

The basic behavior for a BuildStep is to:

run for a while, then stop
possibly invoke some RemoteCommands on the attached worker
possibly produce a set of log files
finish with a status described by one of four values defined in buildbot.process.results: SUCCESS, WARNINGS, FAILURE, SKIPPED
provide a list of short strings to describe the step

The rest of this section describes all the standard BuildStep objects available for use in a Build, and the parameters that can be used to control each. A full list of build steps is available in the Build Step Index.

2.5.12.58. Build steps 

The following build steps are available:

Parameters Common to all Steps
Source checkout steps - used to checkout the source code
- Common Parameters of source checkout operations
- Bzr
- CVS
- Darcs
- Git
- Gerrit
- GitHub
- GitLab
- Mercurial
- Monotone
- P4
- Repo
- SVN
Other source-related steps - used to perform non-checkout source operations
- GitCommit
- GitTag
- GitPush
- GitDiffInfo
ShellCommand steps - used to perform various shell-based operations
- ShellCommand
- Shell Sequence
- Compile
- Configure
- CMake
- Visual C++ (VC<...>, VS<...>, VCExpress9, MsBuild<...)
- Cppcheck
- Robocopy
- Test
- TreeSize
- PerlModuleTest
- SubunitShellCommand
- HLint
- MaxQ
Trigger - triggering other builds
Python build steps - used to perform Python-related build operations
- BuildEPYDoc
- PyFlakes
- Sphinx
- PyLint
- Trial
Debian build steps - used to build deb packages
- DebPbuilder, DebCowBuilder
- DebLintian
RPM build steps - used to build rpm packages
Transferring Files - used to perform file transfer operations
- FileUpload
- FileDownload
- DirectoryUpload
- MultipleFileUpload
- StringDownload
- JSONStringDownload
- JSONPropertiesDownload
HTTP Requests - used to perform HTTP requests
- HTTPStep
- POST
- GET
- PUT
- DELETE
- HEAD
- OPTIONS
Worker Filesystem Steps - used to perform filesystem operations on the worker
- FileExists
- CopyDirectory
- RemoveDirectory
- MakeDirectory
Master steps - used to perform operations on the build master
- MasterShellCommand
- SetProperty
- SetProperties
- SetPropertyFromCommand
- SetPropertiesFromEnv
- LogRenderable - used to log a renderable property for debugging
- Assert - used to terminate build depending on condition

2.5.13. Interlocks

Until now, we assumed that a master can run builds at any worker whenever needed or desired. Some times, you want to enforce additional constraints on builds. For reasons like limited network bandwidth, old worker machines, or a self-willed data base server, you may want to limit the number of builds (or build steps) that can access a resource.

2.5.13.1. Access Modes 

The mechanism used by Buildbot is known as the read/write lock [1]. It allows either many readers or a single writer but not a combination of readers and writers. The general lock has been modified and extended for use in Buildbot. Firstly, the general lock allows an infinite number of readers. In Buildbot, we often want to put an upper limit on the number of readers, for example allowing two out of five possible builds at the same time. To do this, the lock counts the number of active readers. Secondly, the terms read mode and write mode are confusing in the context of Buildbot. They have been replaced by counting mode (since the lock counts them) and exclusive mode. As a result of these changes, locks in Buildbot allow a number of builds (up to some fixed number) in counting mode, or they allow one build in exclusive mode.

Note

Access modes are specified when a lock is used. That is, it is possible to have a single lock that is used by several workers in counting mode, and several workers in exclusive mode. In fact, this is the strength of the modes: accessing a lock in exclusive mode will prevent all counting-mode accesses.

2.5.13.2. Count 

Often, not all workers are equal. To address this situation, Buildbot allows to have a separate upper limit on the count for each worker. In this way, for example, you can have at most 3 concurrent builds at a fast worker, 2 at a slightly older worker, and 1 at all other workers. You can also specify the count during an access request. This specifies how many units an access consumes from the lock (in other words, as how many builds a build will count). This way, you can balance a shared resource that builders consume unevenly, for example, the amount of memory or the number of CPU cores.

2.5.13.3. Scope 

The final thing you can specify when you introduce a new lock is its scope. Some constraints are global and must be enforced on all workers. Other constraints are local to each worker. A master lock is used for the global constraints. You can ensure for example that at most one build (of all builds running at all workers) accesses the database server. With a worker lock you can add a limit local to each worker. With such a lock, you can for example enforce an upper limit to the number of active builds at a worker, like above.

2.5.13.4. Examples 

Time for a few examples. A master lock is defined below to protect a database, and a worker lock is created to limit the number of builds at each worker.

from buildbot.plugins import util

db_lock = util.MasterLock("database")
build_lock = util.WorkerLock("worker_builds",
                             maxCount=1,
                             maxCountForWorker={'fast': 3, 'new': 2})

db_lock is defined to be a master lock. The database string is used for uniquely identifying the lock. At the next line, a worker lock called build_lock is created with the name worker_builds. Since the requirements of the worker lock are a bit more complicated, two optional arguments are also specified. The maxCount parameter sets the default limit for builds in counting mode to 1. For the worker called 'fast' however, we want to have at most three builds, and for the worker called 'new', the upper limit is two builds running at the same time.

The next step is accessing the locks in builds. Buildbot allows a lock to be used during an entire build (from beginning to end) or only during a single build step. In the latter case, the lock is claimed for use just before the step starts and released again when the step ends. To prevent deadlocks [2], it is not possible to claim or release locks at other times.

To use locks, you add them with a locks argument to a build or a step. Each use of a lock is either in counting mode (that is, possibly shared with other builds) or in exclusive mode, and this is indicated with the syntax lock.access(mode, count), where mode is one of "counting" or "exclusive".

The optional argument count is a non-negative integer (for counting locks) or 1 (for exclusive locks). If unspecified, it defaults to 1. If 0, the access always succeeds. This argument allows to use locks for balancing a shared resource that is utilized unevenly.

A build or build step proceeds only when it has acquired all locks. If a build or step needs many locks, it may be starved [3] by other builds requiring fewer locks.

To illustrate the use of locks, here are a few examples.

from buildbot.plugins import util, steps

db_lock = util.MasterLock("database")
build_lock = util.WorkerLock("worker_builds",
                             maxCount=1,
                             maxCountForWorker={'fast': 3, 'new': 2})

f = util.BuildFactory()
f.addStep(steps.SVN(repourl="http://example.org/svn/Trunk"))
f.addStep(steps.ShellCommand(command="make all"))
f.addStep(steps.ShellCommand(command="make test",
                             locks=[db_lock.access('exclusive')]))

b1 = {'name': 'full1', 'workername': 'fast',  'builddir': 'f1', 'factory': f,
       'locks': [build_lock.access('counting')] }

b2 = {'name': 'full2', 'workername': 'new',   'builddir': 'f2', 'factory': f,
       'locks': [build_lock.access('counting')] }

b3 = {'name': 'full3', 'workername': 'old',   'builddir': 'f3', 'factory': f,
       'locks': [build_lock.access('counting')] }

b4 = {'name': 'full4', 'workername': 'other', 'builddir': 'f4', 'factory': f,
       'locks': [build_lock.access('counting')] }

c['builders'] = [b1, b2, b3, b4]

Here we have four workers fast, new, old, and other. Each worker performs the same checkout, make, and test build step sequence. We want to enforce that at most one test step is executed between all workers due to restrictions with the database server. This is done by adding the locks= parameter to the third step. It takes a list of locks with their access mode. Alternatively, this can take a renderable that returns a list of locks with their access mode.

In this case, only the db_lock is needed. The exclusive access mode is used to ensure there is at most one worker that executes the test step.

In addition to exclusive access to the database, we also want workers to stay responsive even under the load of a large number of builds being triggered. For this purpose, the worker lock called build_lock is defined. Since the restraint holds for entire builds, the lock is specified in the builder with 'locks': [build_lock.access('counting')].

Note that you will occasionally see lock.access(mode) written as LockAccess(lock, mode). The two are equivalent, but the former is preferred.

2.5.14. Report Generators

2.5.14.1. BuildStatusGenerator

class buildbot.reporters.BuildStatusGenerator

This report generator sends a message when a build completes. In case a reporter is used to provide a live status notification for both build start and completion, BuildStartEndStatusGenerator is a better option.

The following parameters are supported:

subject

(string, optional).

Deprecated since Buildbot 3.5. Please use the subject argument of the message_formatter passed to the generator.

A string to be used as the subject line of the message. %(builder)s will be replaced with the name of the builder which provoked the message. %(result)s will be replaced with the name of the result of the build. %(title)s and %(projectName)s will be replaced with the title of the Buildbot instance.

mode

(list of strings or a string, optional). Defines the cases when a message should be sent. There are two strings which can be used as shortcuts instead of the full lists.

The possible shortcuts are:

all: Send message for all cases. Equivalent to ('change', 'failing', 'passing', 'problem', 'warnings', 'exception').
warnings: Equivalent to ('warnings', 'failing').

If the argument is list of strings, it must be a combination of:

cancelled: Send message about builds which were cancelled.
change: Send message about builds which change status.
failing: Send message about builds which fail.
passing: Send message about builds which succeed.
problem: Send message about a build which failed when the previous build has passed.
warnings: Send message about builds which generate warnings.
exception: Send message about builds which generate exceptions.

Defaults to ('failing', 'passing', 'warnings').

builders

(list of strings, optional). A list of builder names to serve build status information for. Defaults to None (all builds). Use either builders or tags, but not both.

tags

(list of strings, optional). A list of tag names to serve build status information for. Defaults to None (all tags). Use either builders or tags, but not both.

schedulers

(list of strings, optional). A list of scheduler names to serve build status information for. Defaults to None (all schedulers).

branches

(list of strings, optional). A list of branch names to serve build status information for. Defaults to None (all branches).

add_logs

(boolean or a list of strings, optional). If True, include all build logs as attachments to the messages. These can be quite large. This can also be set to a list of log names to send a subset of the logs. Defaults to False.

add_patch

(boolean, optional). If True, include the patch content if a patch was present. Patches are usually used on a Try server. Defaults to False.

report_new

(boolean, optional) Whether new builds will be reported in addition to finished builds. Defaults to False.

message_formatter

(optional, instance of reporters.MessageFormatter) This is an optional instance of the reporters.MessageFormatter class that can be used to generate a custom message.

2.5.14.2. BuildStartEndStatusGenerator

class buildbot.plugins.reporters.BuildStartEndStatusGenerator

This report generator that sends a message both when a build starts and finishes.

The following parameters are supported:

builders: (list of strings, optional). A list of builder names to serve build status information for. Defaults to None (all builds). Use either builders or tags, but not both.
tags: (list of strings, optional). A list of tag names to serve build status information for. Defaults to None (all tags). Use either builders or tags, but not both.
schedulers: (list of strings, optional). A list of scheduler names to serve build status information for. Defaults to None (all schedulers).
branches: (list of strings, optional). A list of branch names to serve build status information for. Defaults to None (all branches).
add_logs: (boolean or a list of strings, optional). If True, include all build logs as attachments to the messages. These can be quite large. This can also be set to a list of log names to send a subset of the logs. Defaults to False.
add_patch: (boolean, optional). If True, include the patch content if a patch was present. Patches are usually used on a Try server. Defaults to False.
start_formatter: (optional, instance of reporters.MessageFormatter or reporters.MessageFormatterRenderable) This is an optional message formatter that can be used to generate a custom message at the start of the build.
end_formatter: (optional, instance of reporters.MessageFormatter or reporters.MessageFormatterRenderable) This is an optional message formatter that can be used to generate a custom message at the end of the build.

2.5.14.3. BuildSetStatusGenerator

class buildbot.reporters.BuildSetStatusGenerator

This report generator sends a message about builds in a buildset.

Message formatters are invoked for each matching build in the buildset. The collected messages are then joined and sent as a single message. BuildStatusGenerator report generator uses the same message generation logic, but a single, not multiple builds.

In case of multiple builds, the following algorithm is used to build the final message:

message body is merged from bodies provided by message formatters for the builds. If message bodies are lists or strings, then the result is simple concatenation. If the type is different or there is type mismatch, then mismatching messages are ignored.

message subject is taken from the first build for which message formatter a subject.

extra information is merged from the information dictionaries provided by message formatters. Note that extra information is specified as dictionary of dictionaries. Two root dictionaries are merged by merging child dictionaries. Values in merged child dictionaries that conflict (i.e. correspond to the same keys) are resolved by taking the value of the first build for which it is provided.

The following parameters are supported:

subject

(string, optional).

Deprecated since Buildbot 3.5. Please use the subject argument of the message_formatter passed to the generator.

mode

(list of strings or a string, optional). Defines the cases when a message should be sent. Only information about builds that matched the mode will be included. There are two strings which can be used as shortcuts instead of the full lists.

The possible shortcuts are:

all: Send message for all cases. Equivalent to ('change', 'failing', 'passing', 'problem', 'warnings', 'exception').
warnings: Equivalent to ('warnings', 'failing').

If the argument is list of strings, it must be a combination of:

cancelled: Include builds which were cancelled.
change: Include builds which change status.
failing: Include builds which fail.
passing: Include builds which succeed.
problem: Include a build which failed when the previous build has passed.
warnings: Include builds which generate warnings.
exception: Include builds which generate exceptions.

Defaults to ('failing', 'passing', 'warnings').

builders

(list of strings, optional). A list of builder names to serve build status information for. Defaults to None (all builds). Use either builders or tags, but not both.

tags

(list of strings, optional). A list of tag names to serve build status information for. Defaults to None (all tags). Use either builders or tags, but not both.

schedulers

(list of strings, optional). A list of scheduler names to serve build status information for. Defaults to None (all schedulers).

branches

(list of strings, optional). A list of branch names to serve build status information for. Defaults to None (all branches).

add_logs

add_patch

(boolean, optional). If True, include the patch content if a patch was present. Patches are usually used on a Try server. Defaults to False.

message_formatter

(optional, instance of reporters.MessageFormatter) This is an optional instance of the reporters.MessageFormatter class that can be used to generate a custom message.

2.5.14.4. BuildSetCombinedStatusGenerator

class buildbot.reporters.BuildSetCombinedStatusGenerator

This report generator sends a message about a buildset.

Message formatter is invoked only once for all builds in the buildset.

It is very similar to BuildSetCombinedStatusGenerator but invokes message formatters for each matching build in the buildset. The collected messages are then joined and sent as a single message.

A buildset without any builds is useful as a means to report to code review system that a particular code version does not need to be tested. For example in cases when a pull request is updated with the only difference being commit message being changed.

The following parameters are supported:

message_formatter: (instance of reporters.MessageFormatter) This is an instance of the reporters.MessageFormatter class that will be used to generate message for the buildset.

2.5.14.5. WorkerMissingGenerator

class buildbot.reporters.WorkerMissingGenerator

This report generator sends a message when a worker goes missing.

The following parameters are supported:

workers: ("all" or a list of strings, optional). Identifies the workers for which to send a message. "all" (the default) means that a message will be sent when any worker goes missing. The list version of the parameter specifies the names of the workers.
message_formatter: (optional, instance of reporters.MessageFormatterMissingWorker) This is an optional instance of the reporters.MessageFormatterMissingWorker class that can be used to generate a custom message.

2.5.14.6. MessageFormatter

This formatter is used to format messages in BuildStatusGenerator and BuildSetStatusGenerator.

It formats a message using the Jinja2 templating language and picks the template either from a string.

The constructor of the class takes the following arguments:

template_type

This indicates the type of the generated template. Use either ‘plain’ (the default) or ‘html’.

template

If set, specifies the template used to generate the message body. If not set, a default template will be used. The default template is selected according to template_type so it may make sense to specify appropriate template_type even if the default template is used.

subject

If set, specifies the template used to generate the message subject. In case of messages generated for multiple builds within a buildset (e.g. from within BuildSetStatusGenerator), the subject of the first message will be used. The is_buildset key of the context can be used to detect such case and adjust the message appropriately.

ctx

This is an extension of the standard context that will be given to the templates. Use this to add content to the templates that is otherwise not available.

Alternatively, you can subclass MessageFormatter and override the buildAdditionalContext in order to grab more context from the data API.

buildbot.reporters.message.buildAdditionalContext(master, ctx)

Parameters:

master – the master object
ctx – the context dictionary to enhance

Returns:

optionally deferred

default implementation will add self.ctx into the current template context

want_properties

This parameter (defaults to True) will extend the content of the given build object with the Properties from the build.

want_steps

This parameter (defaults to False) will extend the content of the given build object with information about the steps of the build. Use it only when necessary as this increases the overhead in terms of CPU and memory on the master.

want_logs

This parameter (defaults to False) will extend the content of the steps of the given build object with the log metadata of each steps from the build. This implies wantSteps to be True. Use it only when mandatory, as this greatly increases the overhead in terms of CPU and memory on the master.

want_logs_content

This parameter (defaults to False) will extend the content of the logs with the log contents of each steps from the build. This implies want_logs and wantSteps to be True. Use it only when mandatory, as this greatly increases the overhead in terms of CPU and memory on the master.

extra_info_cb

This parameter (defaults to None) can be used to customize extra information that is passed to reporters. If set, this argument must be a function that returns a dictionary of dictionaries either directly or via a Deferred. The interpretation of the return value depends on the exact reporter being used.

Context (build)

In the case the message formatter is used to create message for a build the context that is given to the template consists of the following data:

results

The results of the build as an integer. Equivalent to build['results'].

result_names

A collection that allows accessing a textual identifier of build result. The intended usage is result_names[results].

The following are possible values: success, warnings, failure, skipped, exception, retry, cancelled.

buildername

The name of the builder. Equivalent to build['builder']['name']

mode

The mode argument that has been passed to the report generator.

workername

The name of the worker. Equivalent to the workername property of the build or <unknown> if it’s not available.

buildset

The buildset dictionary from data API.

build

The build dictionary from data API. The properties attribute is populated only if want_properties is set to True. It has the following extra properties:

builder

The builder dictionary from the data API that describes the builder of the build.

buildrequest

The buildrequest dictionary from the data API that describes the build request that the build was built for.

buildset

The buildset dictionary from the data API that describes the buildset that the build was built for.

parentbuild

The build dictionary from the data API that describes the parent build. This build is identified by the parent_buildid attribute of the buildset.

parentbuilder

The builder dictionary from the data API that describes the builder of the parent build.

url

URL to the build in the Buildbot UI.

prev_build

The build dictionary from the data API that describes previous build, if any. This attribute is populated only if wantPreviousBuild is set to True.

steps

A list of step dictionaries from the data API that describe steps in the build, if any. This attribute is populated only if wantSteps is set to True.

Additionally, if want_logs is set to True then the step dictionaries will contain logs attribute with a list of log dictionaries from the data API that describe the logs of the step. The log dictionaries will additionally contain url key with URL to the log in the web UI as the value.

Additionally, if want_logs_content is set to True then the log dictionaries will contain contents key with full contents of the log.

is_buildset

A boolean identifying whether the current message will form a larger message that describes multiple builds in a buildset. This mostly concerns generation of the subject as the message bodies will be merged.

projects

A string identifying the projects that the build was built for.

previous_results

Results of the previous build, if available, otherwise None.

status_detected

String that describes the build in terms of current build results, previous build results and mode.

build_url

URL to the build in the Buildbot UI.

buildbot_title

The title of the Buildbot instance as per c['title'] from the master.cfg

buildbot_url

The URL of the Buildbot instance as per c['buildbotURL'] from the master.cfg

blamelist

The list of users responsible for the build.

summary

A string that summarizes the build result.

sourcestamps

A string identifying the source stamps for which the build was made.

Context (buildset)

In the case the message formatter is used to create message for an buildset itself (see BuildSetCombinedStatusGenerator), the context that is given to the template consists of the following data:

results

The results of the buildset as an integer. Equivalent to build['results'].

result_names

A collection that allows accessing a textual identifier of build result. The intended usage is result_names[results].

The following are possible values: success, warnings, failure, skipped, exception, retry, cancelled.

mode

The mode argument that has been passed to the report generator.

buildset

The buildset dictionary from data API.

builds

A list of build dictionaries from data API. The builds are part of the buildset that is being formatted.

is_buildset

Always True.

projects

A string identifying the projects that the buildset was built for.

status_detected

String that describes the build in terms of current buildset results, previous build results and mode.

buildbot_title

The title of the Buildbot instance as per c['title'] from the master.cfg

buildbot_url

The URL of the Buildbot instance as per c['buildbotURL'] from the master.cfg

blamelist

The list of users responsible for the buildset.

sourcestamps

A string identifying the source stamps for which the buildset was made.

Examples

The following examples describe how to get some useful pieces of information from the various data objects:

Name of the builder that generated this event

{{ buildername }}

Title of the BuildMaster

{{ projects }}

MailNotifier mode

{{ mode }} (a combination of change, failing, passing, problem, warnings, exception, all)

URL to build page

{{ build_url }}

URL to Buildbot main page

{{ buildbot_url }}

Status of the build as string.

This require extending the context of the Formatter via the ctx parameter with: ctx={"statuses": util.Results}.

{{ statuses[results] }}

Build text

{{ build['state_string'] }}

Mapping of property names to (values, source)

{{ build['properties'] }}

For instance the build reason (from a forced build)

{{ build['properties']['reason'][0] }}

Worker name

{{ workername }}

List of responsible users

{{ blamelist | join(', ') }}

2.5.14.7. MessageFormatterFunction

This formatter can be used to generate arbitrary messages bodies according to arbitrary calculations.

As opposed to MessageFormatterRenderable, more information is made available to this reporter. As opposed to MessageFormatterFunctionRaw, only the message body can be customized.

class buildbot.reporters.message.MessageFormatterFunction(function, template_type, want_properties=True, want_steps=False, want_logs=False, want_logs_content=False)

Parameters:

function (callable) –
A callable that will be called with a dictionary.

If the message formatter is used to format a build, the dictionary contains build key with the build dictionary as received from the data API.

If the message formatter is used to format a buildset (e.g. when used from BuildSetCombinedStatusGenerator), the dictionary contains the following:
- buildset key with the buildset dictionary as received from the data API.
- builds key with the builds dictionaries as received from the data API.
template_type (string) – either plain, html or json depending on the output of the formatter. JSON output must not be encoded.
want_properties (boolean) – include ‘properties’ in the build dictionary
want_steps (boolean) – include ‘steps’ in the build dictionary
wantLogs (boolean) – deprecated, use want_logs and want_logs_content set to the same value.
want_logs (boolean) – include ‘logs’ in the steps dictionaries. This implies wantSteps=True. This includes only log metadata, for content use want_logs_content.
want_logs_content (boolean) – include logs content in the logs dictionaries. This implies want_logs=True and wantSteps=True. This dumps the full content of logs and may consume lots of memory and CPU depending on the log size.

2.5.14.8. MessageFormatterFunctionRaw

This formatter can be used to generate arbitrary messages according to arbitrary calculations.

As opposed to MessageFormatterFunction, full message information can be customized.

The return value of the provided function must be a dictionary and is interpreted as follows:

body. Body of the message. Most reporters require this to be a string. If not provided, None is used.

type. Type of the message. Must be either plain, html or json. If not provided, "plain" is used.

subject. Subject of the message. Must be a string. If not provided, None is used.

extra_info. Extra information of the message. Must be either None or a dictionary of dictionaries with string keys in both root and child dictionaries. If not provided, None is used.

class buildbot.reporters.message.MessageFormatterFunctionRaw(function, want_properties=True, want_steps=False, want_logs=False, want_logs_content=False)

Parameters:

function (callable) –
A callable that will be called with a two arguments.
- master: An instance of BuildMaster
- ctx: dictionary that contains the same context dictionary as MessageFormatter.
want_properties (boolean) – include ‘properties’ in the build dictionary
want_steps (boolean) – include ‘steps’ in the build dictionary
want_logs (boolean) – include ‘logs’ in the steps dictionaries. This implies want_steps=True. This includes only log metadata, for content use want_logs_content.
want_logs_content (boolean) – include logs content in the logs dictionaries. This implies want_logs=True and want_steps=True. This dumps the full content of logs and may consume lots of memory and CPU depending on the log size.

2.5.14.9. MessageFormatterRenderable

This formatter is used to format messages in BuildStatusGenerator.

It renders any renderable using the properties of the build that was passed by the status generator.

This message formatter does not support formatting complete buildsets ( BuildSetCombinedStatusGenerator).

The constructor of the class takes the following arguments:

template: A renderable that is used to generate the body of the build report.
subject: A renderable that is used to generate the subject of the build report.

2.5.14.10. MessageFormatterMissingWorkers

This formatter is used to format messages in WorkerMissingGenerator.

It formats a message using the Jinja2 templating language and picks the template either from a string or from a file.

The constructor to that class takes the same arguments as MessageFormatter, minus want_logs, want_logs_content, want_properties, want_steps.

template

The content of the template used to generate the body of the mail as string.

template_type

This indicates the type of the generated template. Use either ‘plain’ (the default) or ‘html’.

subject

The content of the subject of the mail as string.

ctx

This is an extension of the standard context that will be given to the templates. Use this to add content to the templates that is otherwise not available.

Alternatively, you can subclass MessageFormatter and override the buildAdditionalContext in order to grab more context from the data API.

buildbot.reporters.message.buildAdditionalContext(master, ctx)

Parameters:

master – the master object
ctx – the context dictionary to enhance

Returns:

optionally deferred

The default implementation will add self.ctx into the current template context

The default ctx for the missing worker email is made of:

buildbot_title

The title of the Buildbot instance as per c['title'] from the master.cfg

buildbot_url

The URL of the Buildbot instance as per c['buildbotURL'] from the master.cfg

worker

The worker object as defined in the REST api plus two attributes:

notify: List of emails to be notified for this worker.
last_connection: String describing the approximate time of last connection for this worker.

Report generators abstract the conditions of when a message is sent by a Reporter and the content of the message.

Multiple report generators can be registered to a reporter.

At this moment, only the following reporters support report generators:

BitbucketServerPRCommentPush

BitbucketStatusPush

GitHubStatusPush

GitHubCommentPush

GitLabStatusPush

HttpStatusPush

MailNotifier

PushjetNotifier

PushoverNotifier

Eventually, report generator support will be added to the rest of the reporters as well.

The following report generators are available:

BuildStatusGenerator

BuildStartEndStatusGenerator

BuildSetStatusGenerator

BuildSetCombinedStatusGenerator

WorkerMissingGenerator

The report generators may customize the reports using message formatters. The following message formatter classes are provided:

MessageFormatter (commonly used in BuildStatusGenerator, BuildStartEndStatusGenerator, BuildSetCombinedStatusGenerator and BuildSetStatusGenerator)

MessageFormatterRenderable (commonly used in BuildStatusGenerator and BuildStartEndStatusGenerator)

MessageFormatterFunction (commonly used in BuildStatusGenerator and BuildStartEndStatusGenerator)

MessageFormatterFunctionRaw (commonly used in BuildStatusGenerator, BuildStartEndStatusGenerator, BuildSetCombinedStatusGenerator and BuildSetStatusGenerator)

MessageFormatterMissingWorkers (commonly used in WorkerMissingGenerator)

Message formatters produce the following information that is later used by the report generators:

Message type: plain (text), html or json.

Message body: a string that describes the information about build or buildset. Other data types are supported too, but then the interpretation of data depends on actual reporter that is being used.

Message subject: an optional title of the message about build or buildset.

Extra information: optional dictionary of dictionaries with any extra information to give to the reporter. Interpretation of the data depends on the reporter that is being used.

2.5.15. Reporters

2.5.15.1. ReporterBase

class buildbot.reporters.base.ReporterBase(generators)

ReporterBase is a base class used to implement various reporters. It accepts a list of report generators which define what messages to issue on what events. If generators decide that an event needs a report, then the sendMessage function is called. The sendMessage function should be implemented by deriving classes.

Parameters:: generators – (a list of report generator instances) A list of report generators to manage.

sendMessage(self, reports)

Sends the reports via the mechanism implemented by the specific implementation of the reporter. The reporter is expected to interpret all reports, figure out the best mechanism for reporting and report the given information.

Note

The API provided by the sendMessage function is not yet stable and is subject to change.

Parameters:: reports – A list of dictionaries, one for each generator that provided a report.

Frequently used report keys

Note

The list of report keys and their meanings are currently subject to change.

This documents frequently used keys within the dictionaries that are passed to the sendMessage function.

body: (string)
The body of the report to be sent, usually sent as the body of e.g. email.

subject: (string or None)
The subject of the report to be sent or None if nothing was supplied.

type: (string)
The type of the body of the report. The following are currently supported: plain and html.

builder_name: (string)
The name of the builder corresponding to the build or buildset that the report describes.

results: (an instance of a result value from buildbot.process.results)
The current result of the build.

builds (a list of build dictionaries as reported by the data API)
A list of builds that the report describes.

buildset (a buildset dictionary as reported by the data API)
The buildset that is being described.

users (a list of strings)
A list of users to send the report to.

patches (a list of patch dictionaries corresponding to sourcestamp’s patch values)
A list of patches applied to the build or buildset that is being built.

logs (a list of dictionaries corresponding to logs as reported by the data API)
A list of logs produced by the build(s) so far. The following two keys are provided in addition to what the data API provides:

stepname (string) The name of the step that produced the log.

content (string) The content of the log.

extra_info (a dictionary of dictionaries with string keys in both)
A list of additional reporter-specific data to apply.

2.5.15.2. BitbucketServerCoreAPIStatusPush

from buildbot.plugins import reporters

ss = reporters.BitbucketServerCoreAPIStatusPush('https://bitbucketserver.example.com:8080/',
                                                auth=('bitbucketserver_username',
                                                      'secret_password'))
c['services'].append(ss)

Or using Bitbucket personal access token

from buildbot.plugins import reporters

ss = reporters.BitbucketServerCoreAPIStatusPush('https://bitbucketserver.example.com:8080/',
                                                token='MDM0MjM5NDc2MDxxxxxxxxxxxxxxxxxxxxx')
c['services'].append(ss)

BitbucketServerCoreAPIStatusPush publishes build status using BitbucketServer Core REST API into which it was integrated in Bitbucket Server 7.4. The build status is published to a specific commit SHA in specific repository in Bitbucket Server with some additional information about reference name, build duration, parent relationship and also possibly test results.

It requires txrequests package to allow interaction with Bitbucket Server REST API.

class BitbucketServerCoreAPIStatusPush(base_url, token=None, auth=None, name=None, statusSuffix=None, generators=None, key=None, parentName=None, buildNumber=None, ref=None, duration=None, testResults=None, verbose=False, debug=None, verify=None)

Parameters:

base_url (string) – The base url of the Bitbucket Server host.
token (string) – Bitbucket personal access token (mutually exclusive with auth) (can be a Secret)
auth (tuple) – A tuple of Bitbucket Server username and password (mutually exclusive with token) (can be a Secret)
statusName (renderable string) – The name that is displayed for this status. If not defined it is constructed to look like “%(prop:buildername)s #%(prop:buildnumber)s”. Or if the plan has a parent plan the default is constructed to look like “<parent’s buildername> #<parent’s buildnumber> >> %(prop:buildername)s #%(prop:buildnumber)s”. If build status is generated by BuildRequestGenerator “%(prop:buildername)s #(build request)” is used instead of “%(prop:buildername)s #%(prop:buildnumber)s”. Note: Parent information is not accessible as properties for user defined renderer.
statusSuffix (renderable string) – Additional string that is appended to statusName. Empty by default. It is useful when the same plan is launched multiple times for a single parent plan instance. This way every instance of the child plan can have unique suffix and thus be more recognizable (than it would be just by the buildnumber).
generators (list of IReportGenerator instances) – A list of report generators that will be used to generate reports to be sent by this reporter. By default build statuses are generated by BuildRequestGenerator and BuildStartEndStatusGenerator.
key (renderable string) – Passed to Bitbucket Server to differentiate between statuses. A static string can be passed or Interpolate for dynamic substitution. The default key is %(prop:buildername)s.
parentName (renderable string) – Defaults to parent’s buildername if plan has a parent plan. Otherwise plan’s own buildername is used as default.
buildNumber (renderable string) – The default build number is %(prop:buildername)s.
ref (renderable string) – By default branch name from SourceStamp is used. If branch doesn’t start with string refs/ prefix refs/heads/ is added to it’s beginning.
duration (renderable int) – Computed for finished builds. Otherwise None. (value in milliseconds)
testResults (renderable dict) – Test results can be reported via this parameter. Resulting dictionary must contain keys failed, skipped, successful. By default these keys are filled with values from build properties (tests_failed, tests_skipped, tests_successful) if at least one of the properties is found (missing values will default to 0). Otherwise None. Note: If you want to suppress the default behavior pass renderable that always interpolates to None.
verbose (boolean) – If True, logs a message for each successful status push.
verify (boolean) – Disable ssl verification for the case you use temporary self signed certificates.
debug (boolean) – Logs every requests and their response.

2.5.15.3. BitbucketServerPRCommentPush

from buildbot.plugins import reporters

ss = reporters.BitbucketServerPRCommentPush('https://bitbucket-server.example.com:8080/',
                                            'bitbucket_server__username',
                                            'secret_password')
c['services'].append(ss)

BitbucketServerPRCommentPush publishes a comment on a PR using Bitbucket Server REST API.

class buildbot.reporters.bitbucketserver.BitbucketServerPRCommentPush(base_url, user, password, verbose=False, debug=None, verify=None, mode=('failing', 'passing', 'warnings'), tags=None, generators=None)

The following parameters are accepted by this reporter:

base_url: (string) The base url of the Bitbucket server host.
user: (string) The Bitbucket server user to post as. (can be a Secret)
password: (string) The Bitbucket server user’s password. (can be a Secret)
generators: (list) A list of instances of IReportGenerator which defines the conditions of when the messages will be sent and contents of them. See Report Generators for more information.
verbose: (boolean, defaults to False) If True, logs a message for each successful status push.
debug: (boolean, defaults to False) If True, logs every requests and their response
verify: (boolean, defaults to None) If False, disables SSL verification for the case you use temporary self signed certificates. Default enables SSL verification.

Note

This reporter depends on the Bitbucket server hook to get the pull request url.

2.5.15.4. BitbucketServerStatusPush

from buildbot.plugins import reporters

ss = reporters.BitbucketServerStatusPush('https://bitbucketserver.example.com:8080/',
                                         'bitbucketserver_username',
                                         'secret_password')
c['services'].append(ss)

BitbucketServerStatusPush publishes build status using BitbucketServer Build Integration REST API. The build status is published to a specific commit SHA in Bitbucket Server. It tracks the last build for each builderName for each commit built.

Specifically, it follows the Updating build status for commits document.

It requires txrequests package to allow interaction with Bitbucket Server REST API.

It uses HTTP Basic AUTH. As a result, we recommend you use https in your base_url rather than http.

class BitbucketServerStatusPush(base_url, user, password, key=None, statusName=None, generators=None, verbose=False)

Parameters:

base_url (string) – The base url of the Bitbucket Server host, up to and optionally including the first / of the path.
user (string) – The Bitbucket Server user to post as. (can be a Secret)
password (string) – The Bitbucket Server user’s password. (can be a Secret)
key (renderable string) – Passed to Bitbucket Server to differentiate between statuses. A static string can be passed or Interpolate for dynamic substitution. The default key is %(prop:buildername)s.
statusName (renderable string) – The name that is displayed for this status. The default name is nothing, so Bitbucket Server will use the key parameter.
generators (list of IReportGenerator instances) – A list of report generators that will be used to generate reports to be sent by this reporter. Currently the reporter will consider only the report generated by the first generator.
verbose (boolean) – If True, logs a message for each successful status push.
verify (boolean) – Disable ssl verification for the case you use temporary self signed certificates
debug (boolean) – Logs every requests and their response

2.5.15.5. BitbucketStatusPush

from buildbot.plugins import reporters

c['services'].append(reporters.BitbucketStatusPush('oauth_key', 'oauth_secret'))

BitbucketStatusPush publishes build status using the Bitbucket Build Status API. The build status is published to a specific commit SHA in Bitbucket. By default, it tracks the last build for each builder and each commit built.

It requires txrequests package to allow interaction with the Bitbucket REST and OAuth APIs.

It uses OAuth 2.x to authenticate with Bitbucket. To enable this, you need to go to your Bitbucket Settings -> OAuth page. Click “Add consumer”. Give the new consumer a name, e.g. buildbot, and put in any URL as the callback (this is needed for Oauth 2.x, but it’s not used by this reporter), e.g. http://localhost:8010/callback. Give the consumer Repositories:Write access. After creating the consumer, you will then be able to see the OAuth key and secret.

class buildbot.reporters.bitbucket.BitbucketStatusPush(oauth_key=None, oauth_secret=None, auth=None, base_url='https://api.bitbucket.org/2.0/repositories', oauth_url='https://bitbucket.org/site/oauth2/access_token', status_key=None, status_name=None, generators=None)

Parameters:

oauth_key (string) – The OAuth consumer key, when using OAuth to authenticate (can be a Secret)
oauth_secret (string) – The OAuth consumer secret, when using OAuth to authenticate (can be a Secret)
auth (string) – The username,password tuple if using App passwords to authenticate (can be a Secret)
base_url (string) – Bitbucket’s Build Status API URL
oauth_url (string) – Bitbucket’s OAuth API URL
status_key (string) – Key that identifies a build status. Setting the key to a unique value per build allows to push multiple build statuses to a given commit. A static string can be passed or Interpolate for dynamic substitution. The default key is %(prop:buildername)s
status_name (string) – Name of a build status. It shows up next to the status icon in Bitbucket. A static string can be passed or Interpolate for dynamic substitution. The default name is %(prop:buildername)s
generators – A list of report generators that will be used to generate reports to be sent by this reporter. Currently the reporter will consider only the report generated by the first generator. The subject of the report will be used to set the description of the build status. The default subject is an empty string
verify (boolean) – Disable ssl verification for the case you use temporary self signed certificates
debug (boolean) – Logs every requests and their response

For example, the following reporter

from buildbot.plugins import reporters

reporters.BitbucketStatusPush(
    'oauth_key', 'oauth_secret',
    status_key=Interpolate("%(prop:buildername)s/%(prop:buildnumber)s"),
    status_name=Interpolate("%(prop:buildername)s/%(prop:buildnumber)s"),
    generators=[
        reporters.BuildStartEndStatusGenerator(
            start_formatter=reporters.MessageFormatter(subject="{{ status_detected }}"),
            end_formatter=reporters.MessageFormatter(subject="{{ status_detected }}"))
    ])
c['services'].append(ss)

produces the build statuses below when a build stars and ends, respectively.

2.5.15.6. GerritStatusPush

GerritStatusPush sends review of the Change back to the Gerrit server, optionally also sending a message when a build is started. GerritStatusPush can send a separate review for each build that completes, or a single review summarizing the results for all of the builds.

class buildbot.reporters.status_gerrit.GerritStatusPush(server, username, reviewCB, startCB, port, reviewArg, startArg, summaryCB, summaryArg, identity_file, builders, notify...)

Parameters:

server (string) – Gerrit SSH server’s address to use for push event notifications.
username (string) – Gerrit SSH server’s username.
identity_file – (optional) Gerrit SSH identity file.
port (int) – (optional) Gerrit SSH server’s port (default: 29418)
notify – (optional) Control who gets notified by Gerrit once the status is posted. The possible values for notify can be found in your version of the Gerrit documentation for the gerrit review command.

Note

By default, a single summary review is sent; that is, a default summaryCB is provided, but no reviewCB or startCB.

Note

If reviewCB or summaryCB do not return any labels, only a message will be pushed to the Gerrit server.

2.5.15.7. GerritVerifyStatusPush

class buildbot.reporters.status_gerrit_verify_status.GerritVerifyStatusPush

GerritVerifyStatusPush sends a verify status to Gerrit using the verify-status Gerrit plugin.

It is an alternate method to GerritStatusPush, which uses the SSH API to send reviews.

The verify-status plugin allows several CI statuses to be sent for the same change, and display them separately in the Gerrit UI.

Most parameters are renderables.

class buildbot.reporters.status_gerrit_verify_status.GerritVerifyStatusPush(baseURL, auth, verification_name=Interpolate('%(prop:buildername)s'), abstain=False, category=None, reporter=None, verbose=False, generators=None, **kwargs)

Parameters:

baseURL (string) – Gerrit HTTP base URL
auth (string) – A requests authentication configuration. (can be a Secret). If Gerrit is configured with BasicAuth, then it shall be ('login', 'password'). If Gerrit is configured with DigestAuth, then it shall be requests.auth.HTTPDigestAuth('login', 'password') from the requests module.
generators (list of IReportGenerator instances) – A list of report generators that will be used to generate reports to be sent by this reporter. Currently the reporter will consider only the report generated by the first generator.
verification_name (renderable string) – The name of the job displayed in the Gerrit UI
abstain (renderable boolean) – Whether this results should be counted as voting
category (renderable boolean) – Category of the build
reporter (renderable boolean) – The user that verified this build
verbose (boolean) – Whether to log every requests
verify (boolean) – Disable ssl verification for the case you use temporary self signed certificates
debug (boolean) – Logs every requests and their response

This reporter is integrated with GerritChangeSource, and will update changes detected by this change source.

This reporter can also send reports for changes triggered manually provided that there is a property in the build named gerrit_changes, containing the list of changes that were tested. This property must be a list of dictionaries, containing change_id and revision_id keys, as defined in the revision endpoints of the Gerrit documentation.

2.5.15.8. GitHubCommentPush

from buildbot.plugins import reporters, util

context = Interpolate("bb/%(prop:buildername)s")
c['services'].append(reporters.GitHubCommentPush(token='githubAPIToken', context=context))

GitHubCommentPush publishes a comment on a GitHub PR using GitHub Review Comments API.

It requires txrequests package to allow interaction with GitHub REST API.

It requires a GitHub API token in order to operate. By default, the reporter will only comment at the end of a build unless a custom build report generator is supplied.

You can create a token from your own GitHub - Profile - Applications - Register new application or use an external tool to generate one.

class buildbot.plugins.reporters.GitHubCommentPush(token, context=None, generators=None, baseURL=None, verbose=False)

Parameters:

token (string) – Token used for authentication. (can be a Secret)
context (renderable string) – Passed to GitHub to differentiate between statuses. A static string can be passed or Interpolate for dynamic substitution. The default context is buildbot/%(prop:buildername)s.
generators (list of IReportGenerator instances) – A list of report generators that will be used to generate reports to be sent by this reporter. Currently the reporter will consider only the report generated by the first generator.
baseURL (string) – Specify the github API endpoint if you work with GitHub Enterprise
verbose (boolean) – If True, logs a message for each successful status push

Here’s a complete example of posting build results as a github comment:

@util.renderer
@defer.inlineCallbacks
def getresults(props):
    all_logs=[]
    master = props.master
    steps = yield props.master.data.get(
        ('builders', props.getProperty('buildername'), 'builds',
        props.getProperty('buildnumber'), 'steps'))
    for step in steps:
        if step['results'] == util.Results.index('failure'):
            logs = yield master.data.get(("steps", step['stepid'], 'logs'))
            for l in logs:
                all_logs.append('Step : {0} Result : {1}'.format(
                                    step['name'], util.Results[step['results']]))
                all_logs.append('```')
                l['stepname'] = step['name']
                l['content'] = yield master.data.get(("logs", l['logid'], 'contents'))
                step_logs = l['content']['content'].split('\n')
                include = False
                for i, sl in enumerate(step_logs):
                    all_logs.append(sl[1:])
                all_logs.append('```')
    return '\n'.join(all_logs)

generator = BuildStatusGenerator(message_formatter=MessageFormatterRenderable(getresults))
c['services'].append(GitHubCommentPush(token='githubAPIToken', generators=[generator]))

2.5.15.9. GitHubStatusPush

from buildbot.plugins import reporters, util

context = Interpolate("bb/%(prop:buildername)s")
c['services'].append(reporters.GitHubStatusPush(token='githubAPIToken', context=context))

GitHubStatusPush publishes a build status using the GitHub Status API.

It requires txrequests package to allow interaction with the GitHub REST API.

It requires a GitHub API token in order to operate.

You can create a token from your own GitHub - Profile - Applications - Register new application or use an external tool to generate one.

class buildbot.plugins.reporters.GitHubStatusPush(token, context=None, generators=None, baseURL=None, verbose=False)

Parameters:

token (string) – Token used for authentication. (can be a Secret)
context (renderable string) – Passed to GitHub to differentiate between statuses. A static string can be passed or Interpolate for dynamic substitution. The default context is buildbot/%(prop:buildername)s.
generators (list of IReportGenerator instances) – A list of report generators that will be used to generate reports to be sent by this reporter. Currently the reporter will consider only the report generated by the first generator.
baseURL (string) – Specify the github api endpoint if you work with GitHub Enterprise
verbose (boolean) – If True, logs a message for each successful status push

2.5.15.10. GitLabStatusPush

from buildbot.plugins import reporters

gl = reporters.GitLabStatusPush('private-token', context='continuous-integration/buildbot',
                                baseURL='https://git.yourcompany.com')
c['services'].append(gl)

GitLabStatusPush publishes build status using GitLab Commit Status API. The build status is published to a specific commit SHA in GitLab.

It requires txrequests package to allow interaction with GitLab Commit Status API.

It uses private token auth, and the token owner is required to have at least developer access to each repository. As a result, we recommend you use https in your base_url rather than http.

class buildbot.reporters.gitlab.GitLabStatusPush(token, context=None, baseURL=None, generators=None, verbose=False)

Parameters:

token (string) – Private token of user permitted to update status for commits. (can be a Secret)
context (string) – Name of your build system, e.g. continuous-integration/buildbot
generators (list of IReportGenerator instances) – A list of report generators that will be used to generate reports to be sent by this reporter. Currently the reporter will consider only the report generated by the first generator.
baseURL (string) – The base url of the GitLab host, up to and optionally including the first / of the path. Do not include /api/
verbose (string) – Be more verbose
verify (boolean) – Disable ssl verification for the case you use temporary self signed certificates
debug (boolean) – Logs every requests and their response

2.5.15.11. HttpStatusPush

from buildbot.plugins import reporters
sp = reporters.HttpStatusPush(serverUrl="http://example.com/submit")
c['services'].append(sp)

HttpStatusPush sends HTTP POST requests to serverUrl. The body of request contains json-encoded data of the build as returned by the data API. It is useful to create a status front end outside of Buildbot for better scalability.

It requires either txrequests or treq to be installed to allow interaction with HTTP server.

Note

The json data object sent is completely different from the one that was generated by 0.8.x buildbot. It is indeed generated using data api.

class buildbot.reporters.HttpStatusPush(serverUrl, auth=None, headers=None, generators=None, debug=None, verify=None)

Parameters:

serverUrl (string) – The url where to do the HTTP POST request
auth – The authentication method to use. Refer to the documentation of the requests library for more information.
headers (dict) – Pass custom headers to HTTP request.
generators (list of IReportGenerator instances) – A list of report generators that will be used to generate reports to be sent by this reporter. Currently the reporter will consider only the report generated by the first generator.
debug (boolean) – Logs every requests and their response
verify (boolean) – Disable ssl verification for the case you use temporary self signed certificates
skipEncoding (boolean) – Disables encoding of json data to bytes before pushing to server

Json object spec

The default json object sent is a build object augmented with some more data as follow.

{
    "url": "http://yourbot/path/to/build",
    "<build data api values>": "[...]",
    "buildset": "<buildset data api values>",
    "builder": "<builder data api values>",
    "buildrequest": "<buildrequest data api values>"
}

If you want another format, don’t hesitate to use the format_fn parameter to customize the payload. The build parameter given to that function is of type build, optionally enhanced with properties, steps, and logs information.

2.5.15.12. IRC Bot

class buildbot.reporters.irc.IRC

The IRC reporter creates an IRC bot which will attach to certain channels and be available for status queries. It can also be asked to announce builds as they occur, or be told to shut up.

The IRC Bot in buildbot nine, is mostly a rewrite, and not all functionality has been ported yet. Patches are very welcome for restoring the full functionality.

from buildbot.plugins import reporters
irc = reporters.IRC("irc.example.org", "botnickname",
                 useColors=False,
                 channels=[{"channel": "#example1"},
                           {"channel": "#example2",
                            "password": "somesecretpassword"}],
                 password="mysecretnickservpassword",
                 authz={('force', 'stop'): "authorizednick"}
                 notify_events=[
                   'exception',
                   'problem',
                   'recovery',
                   'worker'
                 ])
c['services'].append(irc)

The following parameters are accepted by this class:

host

(mandatory) The IRC server address to connect to.

nick

(mandatory) The name this bot will use on the IRC server.

channels

(mandatory) This is a list of channels to join on the IRC server. Each channel can be a string (e.g. #buildbot), or a dictionary {'channel': '#buildbot', 'password': 'secret'} if each channel requires a different password. A global password can be set with the password parameter.

pm_to_nicks

(optional) This is a list of person to contact on the IRC server.

authz

(optional) Authentication list for commands. It must be a dictionary with command names or tuples of command names as keys. There are two special command names: '' (empty string) meaning any harmless command and '!' for dangerous commands (currently force, stop, and shutdown). The dictionary values are either True of False (which allows or deny commands for everybody) or a list of nicknames authorized to issue specified commands. By default, harmless commands are allowed for everybody and the dangerous ones are prohibited.

A sample authz parameter may look as follows:

authz={
  'version': True,
  '': ['alice', 'bob'],
  ('force', 'stop'): ['alice'],
}

Anybody will be able to run the version command, alice and bob will be allowed to run any safe command and alice will also have the right to force and stop builds.

This parameter replaces older allowForce and allowShutdown, which are deprecated as they were considered a security risk.

Note

The authorization is purely nick-based, so it only makes sense if the specified nicks are registered to the IRC server.

port

(optional, default to 6667) The port to connect to on the IRC server.

tags

(optional) When set, this bot will only communicate about builders containing those tags. (tags functionality is not yet ported)

password

(optional) The global password used to register the bot to the IRC server. If provided, it will be sent to Nickserv to claim the nickname: some IRC servers will not allow clients to send private messages until they have logged in with a password. Can be a Secret.

notify_events

(optional) A list or set of events to be notified on the IRC channels. Available events to be notified are:

started: A build has started.
finished: A build has finished.
success: A build finished successfully.
failure: A build failed.
exception: A build generated and exception.
cancelled: A build was cancelled.
problem: The previous build result was success or warnings, but this one ended with failure or exception.
recovery: This is the opposite of problem: the previous build result was failure or exception and this one ended with success or warnings.
worse: A build state was worse than the previous one (so e.g. it ended with warnings and the previous one was successful).
better: A build state was better than the previous one.
worker: A worker is missing. A notification is also send when the previously reported missing worker connects again.

This parameter can be changed during run-time by sending the notify command to the bot. Note however, that at the buildbot restart or reconfig the notifications listed here will be turned on for the specified channel and nicks. On the other hand, removing events from this parameters will not automatically stop notifications for them (you need to turn them off for every channel with the notify command).

noticeOnChannel: (optional, disabled by default) Whether to send notices rather than messages when communicating with a channel.
showBlameList: (optional, disabled by default) Whether or not to display the blame list for failed builds. (blame list functionality is not ported yet)
useRevisions: (optional, disabled by default) Whether or not to display the revision leading to the build the messages are about. (useRevisions functionality is not ported yet)
useSSL: (optional, disabled by default) Whether or not to use SSL when connecting to the IRC server. Note that this option requires PyOpenSSL.
lostDelay: (optional) Delay to wait before reconnecting to the server when the connection has been lost.
failedDelay: (optional) Delay to wait before reconnecting to the IRC server when the connection failed.
useColors: (optional, enabled by default) The bot can add color to some of its messages. You might turn it off by setting this parameter to False.

The following parameters are deprecated. You must not use them if you use the new authz parameter.

Note

Security Note

Please note that any user having access to your irc channel or can PM the bot will be able to create or stop builds bug #3377. Use authz to give explicit list of nicks who are allowed to do this.

allowForce: (deprecated, disabled by default) This allow all users to force and stop builds via this bot.
allowShutdown: (deprecated, disabled by default) This allow all users to shutdown the master.

To use the service, you address messages at the Buildbot, either normally (botnickname: status) or with private messages (/msg botnickname status). The Buildbot will respond in kind.

If you issue a command that is currently not available, the Buildbot will respond with an error message. If the noticeOnChannel=True option was used, error messages will be sent as channel notices instead of messaging.

Some of the commands currently available:

list builders

Emit a list of all configured builders

status BUILDER

Announce the status of a specific Builder: what it is doing right now.

status all

Announce the status of all Builders

watch BUILDER

If the given Builder is currently running, wait until the Build is finished and then announce the results.

last BUILDER

Return the results of the last build to run on the given Builder.

notify on|off|list EVENT

Report events relating to builds. If the command is issued as a private message, then the report will be sent back as a private message to the user who issued the command. Otherwise, the report will be sent to the channel. Available events to be notified are:

started: A build has started.
finished: A build has finished.
success: A build finished successfully.
failure: A build failed.
exception: A build generated and exception.
cancelled: A build was cancelled.
problem: The previous build result was success or warnings, but this one ended with failure or exception.
recovery: This is the opposite of problem: the previous build result was failure or exception and this one ended with success or warnings.
worse: A build state was worse than the previous one (so e.g. it ended with warnings and the previous one was successful).
better: A build state was better than the previous one.
worker: A worker is missing. A notification is also send when the previously reported missing worker connects again.

By default, this command can be executed by anybody. However, consider limiting it with authz, as enabling notifications in huge number of channels or private chats can cause some problems with your buildbot efficiency.

help COMMAND

Describe a command. Use help commands to get a list of known commands.

source

Announce the URL of the Buildbot’s home page.

version

Announce the version of this Buildbot.

Additionally, the config file may specify default notification options as shown in the example earlier.

If explicitly allowed in the authz config, some additional commands will be available:

join CHANNEL: Join the given IRC channel
leave CHANNEL: Leave the given IRC channel

force build [--codebase=CODEBASE] [--branch=BRANCH] [--revision=REVISION] [--props=PROP1=VAL1,PROP2=VAL2...] BUILDER REASON

Tell the given Builder to start a build of the latest code. The user requesting the build and REASON are recorded in the Build status. The Buildbot will announce the build’s status when it finishes.The user can specify a branch and/or revision with the optional parameters --branch=BRANCH and --revision=REVISION. The user can also give a list of properties with --props=PROP1=VAL1,PROP2=VAL2...

stop build BUILDER REASON

Terminate any running build in the given Builder. REASON will be added to the build status to explain why it was stopped. You might use this if you committed a bug, corrected it right away, and don’t want to wait for the first build (which is destined to fail) to complete before starting the second (hopefully fixed) build.

shutdown ARG

Control the shutdown process of the Buildbot master. Available arguments are:

check: Check if the Buildbot master is running or shutting down
start: Start clean shutdown
stop: Stop clean shutdown
now: Shutdown immediately without waiting for the builders to finish

If the tags is set (see the tags option in Builder Configuration) changes related to only builders belonging to those tags of builders will be sent to the channel.

If the useRevisions option is set to True, the IRC bot will send status messages that replace the build number with a list of revisions that are contained in that build. So instead of seeing build #253 of …, you would see something like build containing revisions [a87b2c4]. Revisions that are stored as hashes are shortened to 7 characters in length, as multiple revisions can be contained in one build and may exceed the IRC message length limit.

Two additional arguments can be set to control how fast the IRC bot tries to reconnect when it encounters connection issues. lostDelay is the number of seconds the bot will wait to reconnect when the connection is lost, where as failedDelay is the number of seconds until the bot tries to reconnect when the connection failed. lostDelay defaults to a random number between 1 and 5, while failedDelay defaults to a random one between 45 and 60. Setting random defaults like this means multiple IRC bots are less likely to deny each other by flooding the server.

2.5.15.13. MailNotifier

class buildbot.reporters.mail.MailNotifier

Buildbot can send emails when builds finish. The most common use of this is to tell developers when their change has caused the build to fail. It is also quite common to send a message to a mailing list (usually named builds or similar) about every build.

The MailNotifier reporter is used to accomplish this. You configure it by specifying who should receive mail, under what circumstances mail should be sent, and how to deliver the mail. It can be configured to only send out mail for certain builders, and only send them when a build fails or when the builder transitions from success to failure. It can also be configured to include various build logs in each message.

If a proper lookup function is configured, the message will be sent to the “interested users” list (Doing Things With Users), which includes all developers who made changes in the build. By default, however, Buildbot does not know how to construct an email address based on the information from the version control system. See the lookup argument, below, for more information.

You can add additional, statically-configured, recipients with the extraRecipients argument. You can also add interested users by setting the owners build property to a list of users in the scheduler constructor (Configuring Schedulers).

Each MailNotifier sends mail to a single set of recipients. To send different kinds of mail to different recipients, use multiple MailNotifiers. TODO: or subclass MailNotifier and override getRecipients()

The following simple example will send an email upon the completion of each build, to just those developers whose Changes were included in the build. The email contains a description of the Build, its results, and URLs where more information can be obtained.

from buildbot.plugins import reporters
mn = reporters.MailNotifier(fromaddr="buildbot@example.org",
                            lookup="example.org")
c['services'].append(mn)

To get a simple one-message-per-build (say, for a mailing list), use the following form instead. This form does not send mail to individual developers (and thus does not need the lookup= argument, explained below); instead it only ever sends mail to the extra recipients named in the arguments:

mn = reporters.MailNotifier(fromaddr="buildbot@example.org",
                            sendToInterestedUsers=False,
                            extraRecipients=['listaddr@example.org'])

If your SMTP host requires authentication before it allows you to send emails, this can also be done by specifying smtpUser and smtpPassword:

mn = reporters.MailNotifier(fromaddr="myuser@example.com",
                            sendToInterestedUsers=False,
                            extraRecipients=["listaddr@example.org"],
                            relayhost="smtp.example.com", smtpPort=587,
                            smtpUser="myuser@example.com",
                            smtpPassword="mypassword")

Note

If for some reasons you are not able to send a notification with TLS enabled and specified user name and password, you might want to use master/contrib/check_smtp.py to see if it works at all.

If you want to require Transport Layer Security (TLS), then you can also set useTls:

mn = reporters.MailNotifier(fromaddr="myuser@example.com",
                            sendToInterestedUsers=False,
                            extraRecipients=["listaddr@example.org"],
                            useTls=True, relayhost="smtp.example.com",
                            smtpPort=587, smtpUser="myuser@example.com",
                            smtpPassword="mypassword")

Note

If you see twisted.mail.smtp.TLSRequiredError exceptions in the log while using TLS, this can be due either to the server not supporting TLS or a missing PyOpenSSL package on the BuildMaster system.

In some cases, it is desirable to have different information than what is provided in a standard MailNotifier message. For this purpose, MailNotifier provides the argument messageFormatter (an instance of MessageFormatter), which allows for creating messages with unique content.

For example, if only short emails are desired (e.g., for delivery to phones):

from buildbot.plugins import reporters

generator = reporters.BuildStatusGenerator(
    mode=('problem',),
    message_formatter=reporters.MessageFormatter(template="STATUS: {{ summary }}"))

mn = reporters.MailNotifier(fromaddr="buildbot@example.org",
                            sendToInterestedUsers=False,
                            extraRecipients=['listaddr@example.org'],
                            generators=[generator])

Another example of a function delivering a customized HTML email is given below:

from buildbot.plugins import reporters

template=u'''\
<h4>Build status: {{ summary }}</h4>
<p> Worker used: {{ workername }}</p>
{% for step in build['steps'] %}
<p> {{ step['name'] }}: {{ step['results'] }}</p>
{% endfor %}
<p><b> -- Buildbot</b></p>
'''

generator = reporters.BuildStatusGenerator(
    mode=('failing',),
    message_formatter=reporters.MessageFormatter(
        template=template, template_type='html',
        want_properties=True, want_steps=True))

mn = reporters.MailNotifier(fromaddr="buildbot@example.org",
                            sendToInterestedUsers=False,
                            mode=('failing',),
                            extraRecipients=['listaddr@example.org'],
                            generators=[generator])

MailNotifier arguments

fromaddr

The email address to be used in the ‘From’ header.

sendToInterestedUsers

(boolean). If True (the default), send mail to all of the Interested Users. Interested Users are authors of changes and users from the owners build property. Override MailNotifier getResponsibleUsersForBuild method to change that. If False, only send mail to the extraRecipients list.

extraRecipients

(list of strings). A list of email addresses to which messages should be sent (in addition to the InterestedUsers list, which includes any developers who made Changes that went into this build). It is a good idea to create a small mailing list and deliver to that, then let subscribers come and go as they please.

generators

(list). A list of instances of IReportGenerator which defines the conditions of when the messages will be sent and contents of them. See Report Generators for more information.

relayhost

(string, deprecated). The host to which the outbound SMTP connection should be made. Defaults to ‘localhost’

smtpPort

(int). The port that will be used on outbound SMTP connections. Defaults to 25.

useTls

(boolean). When this argument is True (default is False), MailNotifier requires that STARTTLS encryption is used for the connection with the relayhost. Authentication is required for STARTTLS so the arguments smtpUser and smtpPassword must also be specified.

useSmtps

(boolean). When this argument is True (default is False), MailNotifier connects to relayhost over an encrypted SSL/TLS connection. This configuration is typically used over port 465.

smtpUser

(string). The user name to use when authenticating with the relayhost. Can be a Secret.

smtpPassword

(string). The password that will be used when authenticating with the relayhost. Can be a Secret.

lookup

(implementer of IEmailLookup). Object which provides IEmailLookup, which is responsible for mapping User names (which come from the VC system) into valid email addresses.

If the argument is not provided, the MailNotifier will attempt to build the sendToInterestedUsers from the authors of the Changes that led to the Build via User Objects. If the author of one of the Build’s Changes has an email address stored, it will added to the recipients list. With this method, owners are still added to the recipients. Note that, in the current implementation of user objects, email addresses are not stored; as a result, unless you have specifically added email addresses to the user database, this functionality is unlikely to actually send any emails.

Most of the time you can use a simple Domain instance. As a shortcut, you can pass as string: this will be treated as if you had provided Domain(str). For example, lookup='example.com' will allow mail to be sent to all developers whose SVN usernames match their example.com account names. See master/buildbot/reporters/mail.py for more details.

Regardless of the setting of lookup, MailNotifier will also send mail to addresses in the extraRecipients list.

extraHeaders

(dictionary). A dictionary containing key/value pairs of extra headers to add to sent e-mails. Both the keys and the values may be an Interpolate instance.

watchedWorkers

This is a list of names of workers, which should be watched. In case a worker goes missing, a notification is sent. The value of watchedWorkers can also be set to all (default) or None. You also need to specify an email address to which the notification is sent in the worker configuration.

dumpMailsToLog

If set to True, all completely formatted mails will be dumped to the log before being sent. This can be useful to debug problems with your mail provider. Be sure to only turn this on if you really need it, especially if you attach logs to emails. This can dump sensitive information to logs and make them very large.

2.5.15.14. PushjetNotifier

class buildbot.reporters.pushover.PushjetNotifier

Pushjet is another instant notification service, similar to PushoverNotifier. To use this reporter, you need to generate a Pushjet service and provide its secret.

The following parameters are accepted by this class:

generators: (list) A list of instances of IReportGenerator which defines the conditions of when the messages will be sent and contents of them. See Report Generators for more information.
secret: This is a secret token for your Pushjet service. See http://docs.pushjet.io/docs/creating-a-new-service to learn how to create a new Pushjet service and get its secret token. Can be a Secret.
levels: Dictionary of Pushjet notification levels. The keys of the dictionary can be change, failing, passing, warnings, exception and are equivalent to the mode strings. The values are integers between 0…5, specifying notification priority. In case a mode is missing from this dictionary, the default value set by Pushover is used.
base_url: Base URL for custom Pushjet instances. Defaults to https://api.pushjet.io.

2.5.15.15. PushoverNotifier

class buildbot.reporters.pushover.PushoverNotifier

Apart of sending mail, Buildbot can send Pushover notifications. It can be used by administrators to receive an instant message to an iPhone or an Android device if a build fails. The PushoverNotifier reporter is used to accomplish this. Its configuration is very similar to the mail notifications, however—due to the notification size constrains—the logs and patches cannot be attached.

To use this reporter, you need to generate an application on the Pushover website https://pushover.net/apps/ and provide your user key and the API token.

The following simple example will send a Pushover notification upon the completion of each build. The notification contains a description of the Build, its results, and URLs where more information can be obtained. The user_key and api_token values should be replaced with proper ones obtained from the Pushover website for your application.

from buildbot.plugins import reporters
pn = reporters.PushoverNotifier(user_key="1234", api_token='abcd')
c['services'].append(pn)

The following parameters are accepted by this class:

generators: (list) A list of instances of IReportGenerator which defines the conditions of when the messages will be sent and contents of them. See Report Generators for more information.
user_key: The user key from the Pushover website. It is used to identify the notification recipient. Can be a Secret.
api_token: API token for a custom application from the Pushover website. Can be a Secret.
priorities: Dictionary of Pushover notification priorities. The keys of the dictionary can be change, failing, passing, warnings, exception and are equivalent to the mode strings. The values are integers between -2…2, specifying notification priority. In case a mode is missing from this dictionary, the default value of 0 is used.
otherParams: Other parameters send to Pushover API. Check https://pushover.net/api/ for their list.

2.5.15.16. Telegram Bot

Buildbot offers a bot, similar to the IRC for Telegram mobile and desktop messaging app. The bot can notify users and groups about build events, respond to status queries, or force and stop builds on request (if allowed to).

In order to use this reporter, you must first speak to BotFather and create a new telegram bot. A quick step-by-step procedure is as follows:

Start a chat with BotFather.
Type /newbot.
Enter a display name for your bot. It can be any string.
Enter a unique username for your bot. Usernames are 5-32 characters long and are case insensitive, but may only include Latin characters, numbers, and underscores. Your bot’s username must end in bot, e.g. MyBuildBot or MyBuildbotBot.
You will be presented with a token for your bot. Save it, as you will need it for TelegramBot configuration.

Optionally, you may type /setcommands, select the username of your new bot and paste the following text:

commands - list available commands
force - force a build
getid - get user and chat ID
hello - say hello
help - give help for a command or one of it's arguments
last - list last build status for a builder
list - list configured builders or workers
nay - forget the current command
notify - notify me about build events
shutdown - shutdown the buildbot master
source - the source code for buildbot
status - list status of a builder (or all builders)
stop - stop a running build
version - show buildbot version
watch - announce the completion of an active build

If you do this, Telegram will provide hints about your bot commands.

If you want, you can set a custom picture and description for your bot.

After setting up the bot in Telegram, you should configure it in Buildbot.

from buildbot.plugins import reporters
telegram = reporters.TelegramBot(
        bot_token='bot_token_given_by_botfather',
        bot_username'username_set_in_botfather_bot',
        chat_ids=[-1234567],
        authz={('force', 'stop'): "authorizednick"}
        notify_events=[
            'exception',
            'problem',
            'recovery',
            'worker'
        ],
        usePolling=True)
c['services'].append(telegram)

The following parameters are accepted by this class:

bot_token: (mandatory) Bot token given by BotFather.
bot_username: (optional) This should be set to the bot unique username defined in BotFather. If this parameter is missing, it will be retrieved from the Telegram server. However, in case of the connection problems, configuration of the Buildbot will be interrupted. For this reason it is advised to set this parameter to the correct value.
chat_ids: (optional) List of chats IDs to send notifications specified in the notify_events parameter. For channels it should have form @channelusername and for private chats and groups it should be a numeric ID. To get it, talk to your bot or add it to a Telegram group and issue /getid command.

Note

In order to receive notification from the bot, you need to talk to it first (and hit the /start button) or add it to the group chat.

authz

(optional) Authentication list for commands. It must be a dictionary with command names (without slashes) or tuples of command names as keys. There are two special command names: '' (empty string) meaning any harmless command and '!' for dangerous commands (currently /force, /stop, and /shutdown). The dictionary values are either True of False (which allows or deny commands for everybody) or a list of numeric IDs authorized to issue specified commands. By default, harmless commands are allowed for everybody and the dangerous ones are prohibited.

A sample authz parameter may look as follows:

authz={
  'getid': True,
  '': [123456, 789012],
  ('force', 'stop'): [123456],
}

Anybody will be able to run the getid command, users with IDs 123456 and 789012 will be allowed to run any safe command and the user with ID 123456 will also have the right to force and stop builds.

tags

(optional) When set, this bot will only communicate about builders containing those tags. (tags functionality is not yet implemented)

notify_events

(optional) A list or set of events to be notified on the Telegram chats. Telegram bot can listen to build ‘start’ and ‘finish’ events. It can also notify about missing workers and their return. This parameter can be changed during run-time by sending the /notify command to the bot. Note however, that at the buildbot restart or reconfig the notifications listed here will be turned on for the specified chats. On the other hand, removing events from this parameters will not automatically stop notifications for them (you need to turn them off for every channel with the /notify command).

showBlameList

(optional, disabled by default) Whether or not to display the blame list for failed builds. (blame list functionality is not yet implemented)

useRevisions

(optional, disabled by default) Whether or not to display the revision leading to the build the messages are about. (useRevisions functionality is not yet implemented)

useWebhook

(optional, disabled by default) By default this bot receives messages from Telegram through polling. You can configure it to use a web-hook, which may be more efficient. However, this requires the web frontend of the Buildbot to be configured and accessible through HTTPS (not HTTP) on a public IP and port number 443, 80, 88, or 8443. Furthermore, the Buildbot configuration option buildbotURL must be correctly set. If you are using HTTP authentication, please ensure that the location buildbotURL/telegrambot_token (e.g. https://buildbot.example.com/telegram123456:secret) is accessible by everybody.

certificate

(optional) A content of your server SSL certificate. This is necessary if the access to the Buildbot web interface is through HTTPS protocol with self-signed certificate and userWebhook is set to True.

pollTimeout

(optional) The time the bot should wait for Telegram to respond to polling using long polling.

retryDelay

(optional) The delay the bot should wait before attempting to retry communication in case of no connection.

To use the service, you sent Telegram commands (messages starting with a slash) to the bot. In most cases you do not need to add any parameters; the bot will ask you about the details.

Some of the commands currently available:

/getid

Get ID of the user and group. This is useful to find the numeric IDs, which should be put in authz and chat_ids configuration parameters.

/list

Emit a list of all configured builders, workers or recent changes.

/status

Announce the status of all builders.

/watch

You will be presented with a list of builders that are currently running. You can select any of them to be notified when the build finishes..

/last

Return the results of the last builds on every builder.

/notify

started: A build has started.
finished: A build has finished.
success: A build finished successfully.
failure: A build failed.
exception: A build generated and exception.
cancelled: A build was cancelled.
problem: The previous build result was success or warnings, but this one ended with failure or exception.
recovery: This is the opposite of problem: the previous build result was failure or exception and this one ended with success or warnings.
worse: A build state was worse than the previous one (so e.g. it ended with warnings and the previous one was successful).
better: A build state was better than the previous one.
worker: A worker is missing. A notification is also send when the previously reported missing worker connects again.

By default this command can be executed by anybody. However, consider limiting it with authz, as enabling notifications in huge number of chats (of any kind) can cause some problems with your buildbot efficiency.

/help

Show short help for the commands.

/commands

List all available commands. If you explicitly type /commands botfather, the bot will respond with a list of commands with short descriptions, to be provided to BotFather.

/source

Announce the URL of the Buildbot’s home page.

/version

Announce the version of this Buildbot.

If explicitly allowed in the authz config, some additional commands will be available:

/force: Force a build. The bot will read configuration from every configured ForceScheduler and present you with the build parameters you can change. If you set all the required parameters, you will be given an option to start the build.
/stop: Stop a build. If there are any active builds, you will be presented with options to stop them.
/shutdown: Control the shutdown process of the Buildbot master. You will be presented with options to start a graceful shutdown, stop it or to shutdown immediately.

If you are in the middle of the conversation with the bot (e.g. it has just asked you a question), you can always stop the current command with a command /nay.

If the tags is set (see the tags option in Builder Configuration) changes related to only builders belonging to those tags of builders will be sent to the channel.

If the useRevisions option is set to True, the IRC bot will send status messages that replace the build number with a list of revisions that are contained in that build. So instead of seeing build #253 of …, you would see something like build containing revisions a87b2c4. Revisions that are stored as hashes are shortened to 7 characters in length, as multiple revisions can be contained in one build and may result in too long messages.

2.5.15.17. ZulipStatusPush

from buildbot.plugins import reporters

zs = reporters.ZulipStatusPush(endpoint='your-organization@zulipchat.com',
                               token='private-token', stream='stream_to_post_in')
c['services'].append(zs)

ZulipStatusPush sends build status using The Zulip API. The build status is sent to a user as a private message or in a stream in Zulip.

class buildbot.reporters.zulip.ZulipStatusPush(endpoint, token, stream=None)

Parameters:

endpoint (string) – URL of your Zulip server
token (string) – Private API token
stream (string) – The stream in which the build status is to be sent. Defaults to None

Note

A private message is sent if stream is set to None.

Json object spec

The json object sent contains the following build status values.

{
    "event": "new/finished",
    "buildid": "<buildid>",
    "buildername": "<builder name>",
    "url": "<URL to the build>",
    "project": "name of the project",
    "timestamp": "<timestamp at start/finish>"
}

The Buildmaster has a variety of ways to present build status to various users. Each such delivery method is a Reporter Target object in the configuration’s services list. To add reporter targets, you just append more objects to this list:

c['services'] = []

m = reporters.MailNotifier(fromaddr="buildbot@localhost",
                           extraRecipients=["builds@lists.example.com"],
                           sendToInterestedUsers=False)
c['services'].append(m)

c['services'].append(reporters.irc.IRC(host="irc.example.com", nick="bb",
                                       channels=[{"channel": "#example1"},
                                                 {"channel": "#example2",
                                                  "password": "somesecretpassword"}]))

Most reporter objects take a tags= argument, which can contain a list of tag names. In this case, the reporters will only show status for Builders that contain the named tags.

Note

Implementation Note

Each of these objects should be a service.BuildbotService which will be attached to the BuildMaster object when the configuration is processed.

The following reporters are available:

BitbucketServerCoreAPIStatusPush

BitbucketServerPRCommentPush

BitbucketServerStatusPush

BitbucketStatusPush

GerritStatusPush

GerritVerifyStatusPush

GitHubCommentPush

GitHubStatusPush

GitLabStatusPush

HttpStatusPush

IRC

MailNotifier

PushjetNotifier

PushoverNotifier

TelegramBot

ZulipStatusPush

Most of the report generators derive from ReporterBase which implements basic reporter management functionality.

2.5.16. Web Server

Note

As of Buildbot 0.9.0, the built-in web server replaces the old WebStatus plugin.

Buildbot contains a built-in web server. This server is configured with the www configuration key, which specifies a dictionary with the following keys:

port

The TCP port on which to serve requests. It might be an integer or any string accepted by serverFromString (ex: “tcp:8010:interface=127.0.0.1” to listen on another interface). Note that using twisted’s SSL endpoint is discouraged. Use a reverse proxy that offers proper SSL hardening instead (see Reverse Proxy Configuration). If this is None (the default), then the master will not implement a web server.

json_cache_seconds

The number of seconds into the future at which an HTTP API response should expire.

rest_minimum_version

The minimum supported REST API version. Any versions less than this value will not be available. This can be used to ensure that no clients are depending on API versions that will soon be removed from Buildbot.

plugins

This key gives a dictionary of additional UI plugins to load, along with configuration for those plugins. These plugins must be separately installed in the Python environment, e.g., pip install buildbot-waterfall-view. See UI plugins. For example:

c['www'] = {
    'plugins': {'waterfall_view': True}
}

default_page

Configure the default landing page of the web server, for example, to forward directly to another plugin. For example:

c['www']['default_page'] = 'console'

debug

If true, then debugging information will be output to the browser. This is best set to false (the default) on production systems, to avoid the possibility of information leakage.

allowed_origins

This gives a list of origins which are allowed to access the Buildbot API (including control via JSONRPC 2.0). It implements cross-origin request sharing (CORS), allowing pages at origins other than the Buildbot UI to use the API. Each origin is interpreted as filename match expression, with ? matching one character and * matching anything. Thus ['*'] will match all origins, and ['https://*.buildbot.net'] will match secure sites under buildbot.net. The Buildbot UI will operate correctly without this parameter; it is only useful for allowing access from other web applications.

auth

Authentication module to use for the web server. See Authentication plugins.

avatar_methods

List of methods that can be used to get avatar pictures to use for the web server. By default, Buildbot uses Gravatar to get images associated with each users, if you want to disable this you can just specify empty list:

c['www'] = {
    'avatar_methods': []
}

You could also use the GitHub user avatar if GitHub authentication is enabled:

c['www'] = {
    'avatar_methods': [util.AvatarGitHub()]
}

class AvatarGitHub(github_api_endpoint=None, token=None, debug=False, verify=False)

Parameters:

github_api_endpoint (string) – specify the github api endpoint if you work with GitHub Enterprise
token (string) – a GitHub API token to execute all requests to the API authenticated. It is strongly recommended to use a API token since it increases GitHub API rate limits significantly
client_id (string) – a GitHub OAuth client ID to use with client secret to execute all requests to the API authenticated in place of token
client_secret (string) – a GitHub OAuth client secret to use with client ID above
debug (boolean) – logs every requests and their response
verify (boolean) – disable ssl verification for the case you use temporary self signed certificates on a GitHub Enterprise installation

This class requires txrequests package to allow interaction with GitHub REST API.

For use of corporate pictures, you can use LdapUserInfo, which can also act as an avatar provider. See Authentication plugins.

logfileName

Filename used for HTTP access logs, relative to the master directory. If set to None or the empty string, the content of the logs will land in the main twisted.log log file. (Defaults to http.log)

logRotateLength

The amount of bytes after which the http.log file will be rotated. (Defaults to the same value as for the twisted.log file, set in buildbot.tac)

maxRotatedFiles

The amount of log files that will be kept when rotating (Defaults to the same value as for the twisted.log file, set in buildbot.tac)

versions

Custom component versions that you’d like to display on the About page. Buildbot will automatically prepend the versions of Python, twisted and Buildbot itself to the list.

versions should be a list of tuples. For example:

c['www'] = {
    # ...
    'versions': [
        ('master.cfg', '0.1'),
        ('OS', 'Ubuntu 14.04'),
    ]
}

The first element of a tuple stands for the name of the component, the second stands for the corresponding version.

custom_templates_dir

This directory will be parsed for custom angularJS templates to replace the one of the original website templates. You can use this to slightly customize buildbot look for your project, but to add any logic, you will need to create a full-blown plugin. If the directory string is relative, it will be joined to the master’s basedir. Buildbot uses the jade file format natively (which has been renamed to ‘pug’ in the nodejs ecosystem), but you can also use HTML format if you prefer.

Either *.jade files or *.html files can be used to override templates with the same name in the UI. On the regular nodejs UI build system, we use nodejs’s pug module to compile jade into html. For custom_templates, we use the pypugjs interpreter to parse the jade templates, before sending them to the UI. pip install pypugjs is required to use jade templates. You can also override plugin’s directives, but they have to be in another directory, corresponding to the plugin’s name in its package.json. For example:

# replace the template whose source is in:
# www/base/src/app/builders/build/build.tpl.jade
build.jade  # here we use a jade (aka pug) file

# replace the template whose source is in
# www/console_view/src/module/view/builders-header/console.tpl.jade
console_view/console.html  # here we use html format

Known differences between nodejs’s pug and pyjade:

quotes in attributes are not quoted (https://github.com/syrusakbary/pyjade/issues/132). This means you should use double quotes for attributes, e.g.: tr(ng-repeat="br in buildrequests | orderBy:'-submitted_at'")

pypugjs may have some differences but it is a maintained fork of pyjade. https://github.com/kakulukia/pypugjs

change_hook_dialects

See Change Hooks.

cookie_expiration_time

This allows to define the timeout of the session cookie. Should be a datetime.timedelta. Default is one week.
import datetime
c['www'] = {
    # ...
    'cookie_expiration_time': datetime.timedelta(weeks=2)
}

ui_default_config

Settings in the settings page are stored per browser. This configuration parameter allows to override the default settings for all your users. If a user already has changed a value from the default, this will have no effect to them. The settings page in the UI will tell you what to insert in your master.cfg to reproduce the configuration you have in your own browser. For example:
c['www']['ui_default_config'] = {
    'Builders.buildFetchLimit': 500,
    'Workers.showWorkerBuilders': True,
}

ws_ping_interval

Send websocket pings every ws_ping_interval seconds. This is useful to avoid websocket timeouts when using reverse proxies or CDNs. If the value is 0 (the default), pings are disabled.

theme

Allows configuring certain properties of the web frontend, such as colors. The configuration value is a dictionary. The keys correspond to certain CSS variable names that are used throughout web frontend and made configurable. The values correspond to CSS values of these variables.

The keys and values are not sanitized, so using data derived from user-supplied information is a security risk.

The default is the following:
c["www"]["theme"] = {
    "bb-sidebar-background-color": "#30426a",
    "bb-sidebar-header-background-color": "#273759",
    "bb-sidebar-header-text-color": "#fff",
    "bb-sidebar-title-text-color": "#627cb7",
    "bb-sidebar-footer-background-color": "#273759",
    "bb-sidebar-button-text-color": "#b2bfdc",
    "bb-sidebar-button-hover-background-color": "#1b263d",
    "bb-sidebar-button-hover-text-color": "#fff",
    "bb-sidebar-button-current-background-color": "#273759",
    "bb-sidebar-button-current-text-color": "#b2bfdc",
    "bb-sidebar-stripe-hover-color": "#e99d1a",
    "bb-sidebar-stripe-current-color": "#8c5e10",
}

Note

The buildbotURL configuration value gives the base URL that all masters will use to generate links. The www configuration gives the settings for the webserver. In simple cases, the buildbotURL contains the hostname and port of the master, e.g., http://master.example.com:8010/. In more complex cases, with multiple masters, web proxies, or load balancers, the correspondence may be less obvious.

2.5.16.1. UI plugins

Waterfall View

Waterfall shows the whole Buildbot activity in a vertical time line. Builds are represented with boxes whose height vary according to their duration. Builds are sorted by builders in the horizontal axes, which allows you to see how builders are scheduled together.

pip install buildbot-waterfall-view

c['www'] = {
    'plugins': {'waterfall_view': True}
}

Note

Waterfall is the emblematic view of Buildbot Eight. It allowed to see the whole Buildbot activity very quickly. Waterfall however had big scalability issues, and larger installs had to disable the page in order to avoid tens of seconds master hang because of a big waterfall page rendering. The whole Buildbot Eight internal status API has been tailored in order to make Waterfall possible. This is not the case anymore with Buildbot Nine, which has a more generic and scalable Data API and REST API. This is the reason why Waterfall does not display the steps details anymore. However nothing is impossible. We could make a specific REST api available to generate all the data needed for waterfall on the server. Please step-in if you want to help improve the Waterfall view.

Console View

Console view shows the whole Buildbot activity arranged by changes as discovered by Change Sources and Changes vertically and builders horizontally. If a builder has no build in the current time range, it will not be displayed. If no change is available for a build, then it will generate a fake change according to the got_revision property.

Console view will also group the builders by tags. When there are several tags defined per builders, it will first group the builders by the tag that is defined for most builders. Then given those builders, it will group them again in another tag cluster. In order to keep the UI usable, you have to keep your tags short!

pip install buildbot-console-view

c['www'] = {
    'plugins': {'console_view': True}
}

Note

Nine’s Console View is the equivalent of Buildbot Eight’s Console and tgrid views. Unlike Waterfall, we think it is now feature equivalent and even better, with its live update capabilities. Please submit an issue if you think there is an issue displaying your data, with screen shots of what happen and suggestion on what to improve.

Grid View

Grid view shows the whole Buildbot activity arranged by builders vertically and changes horizontally. It is equivalent to Buildbot Eight’s grid view.

By default, changes on all branches are displayed but only one branch may be filtered by the user. Builders can also be filtered by tags. This feature is similar to the one in the builder list.

pip install buildbot-grid-view

c['www'] = {
    'plugins': {'grid_view': True}
}

Badges

Buildbot badges plugin produces an image in SVG or PNG format with information about the last build for the given builder name. PNG generation is based on the CAIRO SVG engine, it requires a bit more CPU to generate.

pip install buildbot-badges

c['www'] = {
    'plugins': {'badges': {}}
}

You can the access your builder’s badges using urls like http://<buildbotURL>/plugins/badges/<buildername>.svg. The default templates are very much configurable via the following options:

{
    "left_pad"  : 5,
    "left_text": "Build Status",  # text on the left part of the image
    "left_color": "#555",  # color of the left part of the image
    "right_pad" : 5,
    "border_radius" : 5, # Border Radius on flat and plastic badges
    # style of the template availables are "flat", "flat-square", "plastic"
    "style": "plastic",
    "template_name": "{style}.svg.j2",  # name of the template
    "font_face": "DejaVu Sans",
    "font_size": 11,
    "color_scheme": {  # color to be used for right part of the image
        "exception": "#007ec6",  # blue
        "failure": "#e05d44",    # red
        "retry": "#007ec6",      # blue
        "running": "#007ec6",    # blue
        "skipped": "a4a61d",     # yellowgreen
        "success": "#4c1",       # brightgreen
        "unknown": "#9f9f9f",    # lightgrey
        "warnings": "#dfb317"    # yellow
    }
}

Those options can be configured either using the plugin configuration:

c['www'] = {
    'plugins': {'badges': {"left_color": "#222"}}
}

or via the URL arguments like http://<buildbotURL>/plugins/badges/<buildername>.svg?left_color=222. Custom templates can also be specified in a template directory nearby the master.cfg.

The badgeio template

A badges template was developed to standardize upon a consistent “look and feel” across the usage of multiple CI/CD solutions, e.g.: use of Buildbot, Codecov.io, and Travis-CI. An example is shown below.

To ensure the correct “look and feel”, the following Buildbot configuration is needed:

c['www'] = {
    'plugins': {
        'badges': {
            "left_pad": 0,
            "right_pad": 0,
            "border_radius": 3,
            "style": "badgeio"
        }
    }
}

Note

It is highly recommended to use only with SVG.

2.5.16.2. Authentication plugins

By default, Buildbot does not require people to authenticate in order to access control features in the web UI. To secure Buildbot, you will need to configure an authentication plugin.

Note

To secure the Buildbot web interface, authorization rules must be provided via the ‘authz’ configuration. If you simply wish to lock down a Buildbot instance so that only read only access is permitted, you can restrict access to control endpoints to an unpopulated ‘admin’ role. For example:

c['www']['authz'] = util.Authz(allowRules=[util.AnyControlEndpointMatcher(role="admins")],
                               roleMatchers=[])

Note

As of Buildbot 0.9.4, user session is managed via a JWT token, using HS256 algorithm. The session secret is stored in the database in the object_state table with name column being session_secret. Please make sure appropriate access restriction is made to this database table.

Authentication plugins are implemented as classes, and passed as the auth parameter to www.

The available classes are described here:

class buildbot.www.auth.NoAuth: This class is the default authentication plugin, which disables authentication.

class buildbot.www.auth.UserPasswordAuth(users)

Parameters:: users – list of ("user","password") tuples, or a dictionary of {"user": "password", ..}

Simple username/password authentication using a list of user/password tuples provided in the configuration file.

from buildbot.plugins import util
c['www'] = {
    # ...
    'auth': util.UserPasswordAuth({"homer": "doh!"}),
}

class buildbot.www.auth.CustomAuth

This authentication class means to be overridden with a custom check_credentials method that gets username and password as arguments and check if the user can login. You may use it e.g. to check the credentials against an external database or file.

from buildbot.plugins import util

class MyAuth(util.CustomAuth):
    def check_credentials(self, user, password):
        if user == 'snow' and password == 'white':
            return True
        else:
            return False

from buildbot.plugins import util
c['www']['auth'] = MyAuth()

class buildbot.www.auth.HTPasswdAuth(passwdFile)

Parameters:: passwdFile – An .htpasswd file to read

This class implements simple username/password authentication against a standard .htpasswd file.

from buildbot.plugins import util
c['www'] = {
    # ...
    'auth': util.HTPasswdAuth("my_htpasswd"),
}

class buildbot.www.oauth2.GoogleAuth(clientId, clientSecret)

Parameters:

clientId – The client ID of your buildbot application
clientSecret – The client secret of your buildbot application

This class implements an authentication with Google single sign-on. You can look at the Google oauth2 documentation on how to register your Buildbot instance to the Google systems. The developer console will give you the two parameters you have to give to GoogleAuth.

Example:

from buildbot.plugins import util
c['www'] = {
    # ...
    'auth': util.GoogleAuth("clientid", "clientsecret"),
}

In order to use this module, you need to install the Python requests module:

pip install requests

class buildbot.www.oauth2.GitHubAuth(clientId, clientSecret)

param clientId:

The client ID of your buildbot application

param clientSecret:

The client secret of your buildbot application

param serverURL:

The server URL if this is a GitHub Enterprise server

param apiVersion:

The GitHub API version to use. One of 3 or 4 (V3/REST or V4/GraphQL). Defaults to 3.

param getTeamsMembership:

When True fetch all team memberships for each of the organizations the user belongs to. The teams will be included in the user’s groups as org-name/team-name.

param debug:

When True and using apiVersion=4 show some additional log calls with the GraphQL queries and responses for debugging purposes.

This class implements an authentication with GitHub single sign-on. It functions almost identically to the GoogleAuth class.

Register your Buildbot instance with the BUILDBOT_URL/auth/login url as the allowed redirect URI.

The user’s email-address (for e.g. authorization) is set to the “primary” address set by the user in GitHub. When using group-based authorization, the user’s groups are equal to the names of the GitHub organizations the user is a member of.

Example:
from buildbot.plugins import util
c['www'] = {
    # ...
    'auth': util.GitHubAuth("clientid", "clientsecret"),
}
Example for Enterprise GitHub:
from buildbot.plugins import util
c['www'] = {
    # ...
    'auth': util.GitHubAuth("clientid", "clientsecret",
                            "https://git.corp.mycompany.com"),
}
An example on fetching team membership could be:
from buildbot.plugins import util
c['www'] = {
    # ...
    'auth': util.GitHubAuth("clientid", "clientsecret", apiVersion=4,
                            getTeamsMembership=True),
    'authz': util.Authz(
        allowRules=[
          util.AnyControlEndpointMatcher(role="core-developers"),
        ],
        roleMatchers=[
          util.RolesFromGroups(groupPrefix='buildbot/')
        ]
      )
}

If the buildbot organization had two teams, for example, ‘core-developers’ and ‘contributors’, with the above example, any user belonging to those teams would be granted the roles matching those team names.

In order to use this module, you need to install the Python requests module:

pip install requests

class buildbot.www.oauth2.GitLabAuth(instanceUri, clientId, clientSecret)

Parameters:

instanceUri – The URI of your GitLab instance
clientId – The client ID of your buildbot application
clientSecret – The client secret of your buildbot application

This class implements an authentication with GitLab single sign-on. It functions almost identically to the GoogleAuth class.

Example:

from buildbot.plugins import util
c['www'] = {
    # ...
    'auth': util.GitLabAuth("https://gitlab.com", "clientid", "clientsecret"),
}

In order to use this module, you need to install the Python requests module:

pip install requests

class buildbot.www.oauth2.BitbucketAuth(clientId, clientSecret)

Parameters:

clientId – The client ID of your buildbot application
clientSecret – The client secret of your buildbot application

This class implements an authentication with Bitbucket single sign-on. It functions almost identically to the GoogleAuth class.

Example:

from buildbot.plugins import util
c['www'] = {
    # ...
    'auth': util.BitbucketAuth("clientid", "clientsecret"),
}

In order to use this module, you need to install the Python requests module:

pip install requests

class buildbot.www.auth.RemoteUserAuth

Parameters:

header – header to use to get the username (defaults to REMOTE_USER)
headerRegex – regular expression to get the username from header value (defaults to "(?P<username>[^ @]+)@(?P<realm>[^ @]+)"). Note that you need at least to specify a ?P<username> regular expression named group.
userInfoProvider – user info provider; see User Information

If the Buildbot UI is served through a reverse proxy that supports HTTP-based authentication (like apache or lighttpd), it’s possible to tell Buildbot to trust the web server and get the username from the request headers.

The administrator must make sure that it’s impossible to get access to Buildbot in any way other than through the frontend. Usually this means that Buildbot should listen for incoming connections only on localhost (or on some firewall-protected port). The reverse proxy must require HTTP authentication to access Buildbot pages (using any source for credentials, such as htpasswd, PAM, LDAP, Kerberos).

Example:

from buildbot.plugins import util
c['www'] = {
    # ...
    'auth': util.RemoteUserAuth(),
}

A corresponding Apache configuration example:

<Location "/">
        AuthType Kerberos
        AuthName "Buildbot login via Kerberos"
        KrbMethodNegotiate On
        KrbMethodK5Passwd On
        KrbAuthRealms <<YOUR CORP REALMS>>
        KrbVerifyKDC off
        KrbServiceName Any
        Krb5KeyTab /etc/krb5/krb5.keytab
        KrbSaveCredentials Off
        require valid-user
        Order allow,deny

        Satisfy Any

        #] SSO
        RewriteEngine On
        RewriteCond %{LA-U:REMOTE_USER} (.+)$
        RewriteRule . - [E=RU:%1,NS]
        RequestHeader set REMOTE_USER %{RU}e

</Location>

The advantage of this sort of authentication is that it is uses a proven and fast implementation for authentication. The problem is that the only information that is passed to Buildbot is the username, and there is no way to pass any other information like user email, user groups, etc. That information can be very useful to the mailstatus plugin, or for authorization processes. See User Information for a mechanism to supply that information.

2.5.16.3. User Information

For authentication mechanisms which cannot provide complete information about a user, Buildbot needs another way to get user data. This is useful both for authentication (to fetch more data about the logged-in user) and for avatars (to fetch data about other users).

This extra information is provided, appropriately enough, by user info providers. These can be passed to RemoteUserAuth and as an element of avatar_methods.

This can also be passed to oauth2 authentication plugins. In this case the username provided by oauth2 will be used, and all other information will be taken from ldap (Full Name, email, and groups):

Currently only one provider is available:

class buildbot.ldapuserinfo.LdapUserInfo(uri, bindUser, bindPw, accountBase, accountPattern, groupBase=None, groupMemberPattern=None, groupName=None, accountFullName, accountEmail, avatarPattern=None, avatarData=None, accountExtraFields=None, tls=None)

Parameters:

uri – uri of the ldap server
bindUser – username of the ldap account that is used to get the infos for other users (usually a “faceless” account)
bindPw – password of the bindUser
accountBase – the base dn (distinguished name)of the user database
accountPattern – the pattern for searching in the account database. This must contain the %(username)s string, which is replaced by the searched username
accountFullName – the name of the field in account ldap database where the full user name is to be found.
accountEmail – the name of the field in account ldap database where the user email is to be found.
groupBase – the base dn of the groups database
groupMemberPattern – the pattern for searching in the group database. This must contain the %(dn)s string, which is replaced by the searched username’s dn
groupName – the name of the field in groups ldap database where the group name is to be found.
avatarPattern – the pattern for searching avatars from emails in the account database. This must contain the %(email)s string, which is replaced by the searched email
avatarData – the name of the field in groups ldap database where the avatar picture is to be found. This field is supposed to contain the raw picture, format is automatically detected from jpeg, png or git.
accountExtraFields – extra fields to extracts for use with the authorization policies
tls – an instance of ldap.Tls that specifies TLS settings.

If one of the three optional groups parameters is supplied, then all of them become mandatory. If none is supplied, the retrieved user info has an empty list of groups.

Example:

from buildbot.plugins import util

# this configuration works for MS Active Directory ldap implementation
# we use it for user info, and avatars
userInfoProvider = util.LdapUserInfo(
    uri='ldap://ldap.mycompany.com:3268',
    bindUser='ldap_user',
    bindPw='p4$$wd',
    accountBase='dc=corp,dc=mycompany,dc=com',
    groupBase='dc=corp,dc=mycompany,dc=com',
    accountPattern='(&(objectClass=person)(sAMAccountName=%(username)s))',
    accountFullName='displayName',
    accountEmail='mail',
    groupMemberPattern='(&(objectClass=group)(member=%(dn)s))',
    groupName='cn',
    avatarPattern='(&(objectClass=person)(mail=%(email)s))',
    avatarData='thumbnailPhoto',
)
c['www'] = {
    "port": PORT,
    "allowed_origins": ["*"],
    "url": c['buildbotURL'],
    "auth": util.RemoteUserAuth(userInfoProvider=userInfoProvider),
    "avatar_methods": [
        userInfoProvider,
        util.AvatarGravatar()
    ]
}

Note

In order to use this module, you need to install the ldap3 module:

pip install ldap3

In the case of oauth2 authentications, you have to pass the userInfoProvider as keyword argument:

from buildbot.plugins import util
userInfoProvider = util.LdapUserInfo(...)
c['www'] = {
    # ...
    'auth': util.GoogleAuth("clientid", "clientsecret", userInfoProvider=userInfoProvider),
}

2.5.16.4. Reverse Proxy Configuration

It is usually better to put Buildbot behind a reverse proxy in production.

Provides automatic gzip compression
Provides SSL support with a widely used implementation
Provides support for http/2 or spdy for fast parallel REST api access from the browser

Reverse proxy however might be problematic for websocket, you have to configure it specifically to pass web socket requests. Here is an nginx configuration that is known to work (nginx 1.6.2):

server {
        # Enable SSL and http2
        listen 443 ssl http2 default_server;

        server_name yourdomain.com;

        root html;
        index index.html index.htm;

        ssl on;
        ssl_certificate /etc/nginx/ssl/server.cer;
        ssl_certificate_key /etc/nginx/ssl/server.key;

        # put a one day session timeout for websockets to stay longer
        ssl_session_cache      shared:SSL:10m;
        ssl_session_timeout  1440m;

        # please consult latest nginx documentation for current secure encryption settings
        ssl_protocols ..
        ssl_ciphers ..
        ssl_prefer_server_ciphers   on;
        #

        # force https
        add_header Strict-Transport-Security "max-age=31536000; includeSubdomains;";
        spdy_headers_comp 5;

        proxy_set_header HOST $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto  $scheme;
        proxy_set_header X-Forwarded-Server  $host;
        proxy_set_header X-Forwarded-Host  $host;

        # you could use / if you use domain based proxy instead of path based proxy
        location /buildbot/ {
            proxy_pass http://127.0.0.1:5000/;
        }
        location /buildbot/sse/ {
            # proxy buffering will prevent sse to work
            proxy_buffering off;
            proxy_pass http://127.0.0.1:5000/sse/;
        }
        # required for websocket
        location /buildbot/ws {
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
            proxy_pass http://127.0.0.1:5000/ws;
            # raise the proxy timeout for the websocket
            proxy_read_timeout 6000s;
        }
}

To run with Apache2, you’ll need mod_proxy_wstunnel in addition to mod_proxy_http. Serving HTTPS (mod_ssl) is advised to prevent issues with enterprise proxies (see Server Sent Events), even if you don’t need the encryption itself.

Here is a configuration that is known to work (Apache 2.4.10 / Debian 8, Apache 2.4.25 / Debian 9, Apache 2.4.6 / CentOS 7), directly at the top of the domain.

If you want to add access control directives, just put them in a <Location />.

<VirtualHost *:443>
    ServerName buildbot.example
    ServerAdmin webmaster@buildbot.example

    # replace with actual port of your Buildbot master
    ProxyPass /ws ws://127.0.0.1:8020/ws
    ProxyPassReverse /ws ws://127.0.0.1:8020/ws
    ProxyPass / http://127.0.0.1:8020/
    ProxyPassReverse / http://127.0.0.1:8020/

    SetEnvIf X-Url-Scheme https HTTPS=1
    ProxyPreserveHost On

    SSLEngine on
    SSLCertificateFile /path/to/cert.pem
    SSLCertificateKeyFile /path/to/cert.key

    # check Apache2 documentation for current safe SSL settings
    # This is actually the Debian 8 default at the time of this writing:
    SSLProtocol all -SSLv3

</VirtualHost>

2.5.16.5. Authorization rules

The authorization framework in Buildbot is very generic and flexible. The drawback is that it is not very obvious for newcomers. The ‘simple’ example will however allow you to easily start by implementing an admins-have-all-rights setup.

Please carefully read the following documentation to understand how to setup authorization in Buildbot.

Authorization framework is tightly coupled to the REST API. Authorization framework only works for HTTP, not for other means of interaction like IRC or try scheduler. It allows or denies access to the REST APIs according to rules.

Roles is a label that you give to a user.

It is similar but different to the usual notion of group:
- A user can have several roles, and a role can be given to several users.
- Role is an application specific notion, while group is more organization specific notion.
- Groups are given by the auth plugin, e.g ldap, github, and are not always in the precise control of the buildbot admins.
- Roles can be dynamically assigned, according to the context. For example, there is the owner role, which can be given to a user for a build that he is at the origin, so that he can stop or rebuild only builds of his own.
Endpoint matchers associate role requirements to REST API endpoints. The default policy is allow in case no matcher matches (see below why).
Role matchers associate authenticated users to roles.

Restricting Read Access

Please note that you can use this framework to deny read access to the REST API, but there is no access control in websocket or SSE APIs. Practically this means user will still see live updates from running builds in the UI, as those will come from websocket.

The only resources that are only available for read in REST API are the log data (a.k.a logchunks).

From a strict security point of view you cannot really use Buildbot Authz framework to securely deny read access to your bot. The access control is rather designed to restrict control APIs which are only accessible through REST API. In order to reduce attack surface, we recommend to place Buildbot behind an access controlled reverse proxy like OAuth2Proxy.

Authz Configuration

class buildbot.www.authz.Authz(allowRules=[], roleMatcher=[], stringsMatcher=util.fnmatchStrMatcher)

Parameters:

allowRules – List of EndpointMatcherBase processed in order for each endpoint grant request.
roleMatcher – List of RoleMatchers
stringsMatcher – Selects algorithm used to make strings comparison (used to compare roles and builder names). Can be util.fnmatchStrMatcher or util.reStrMatcher from from buildbot.plugins import util

Authz needs to be configured in c['www']['authz']

Endpoint matchers

Endpoint matchers are responsible for creating rules to match REST endpoints, and requiring roles for them. Endpoint matchers are processed in the order they are configured. The first rule matching an endpoint will prevent further rules from being checked. To continue checking other rules when the result is deny, set defaultDeny=False. If no endpoint matcher matches, then access is granted.

One can implement the default deny policy by putting an AnyEndpointMatcher with nonexistent role in the end of the list. Please note that this will deny all REST apis, and most of the UI do not implement proper access denied message in case of such error.

The following sequence is implemented by each EndpointMatcher class:

Check whether the requested endpoint is supported by this matcher
Get necessary info from data API and decide whether it matches
Look if the user has the required role

Several endpoints matchers are currently implemented. If you need a very complex setup, you may need to implement your own endpoint matchers. In this case, you can look at the source code for detailed examples on how to write endpoint matchers.

class buildbot.www.authz.endpointmatchers.EndpointMatcherBase(role, defaultDeny=True)

Parameters:

role – The role which grants access to this endpoint. List of roles is not supported, but a fnmatch expression can be provided to match several roles.
defaultDeny – The role matcher algorithm will stop if this value is true and the endpoint matched.

This is the base endpoint matcher. Its arguments are inherited by all the other endpoint matchers.

class buildbot.www.authz.endpointmatchers.AnyEndpointMatcher(role)

Parameters:: role – The role which grants access to any endpoint.

AnyEndpointMatcher grants all rights to people with given role (usually “admins”).

class buildbot.www.authz.endpointmatchers.AnyControlEndpointMatcher(role)

Parameters:: role – The role which grants access to any control endpoint.

AnyControlEndpointMatcher grants control rights to people with given role (usually “admins”). This endpoint matcher matches current and future control endpoints. You need to add this in the end of your configuration to make sure it is future proof.

class buildbot.www.authz.endpointmatchers.ForceBuildEndpointMatcher(builder, role)

Parameters:

builder – Name of the builder.
role – The role needed to get access to such endpoints.

ForceBuildEndpointMatcher grants right to force builds.

class buildbot.www.authz.endpointmatchers.StopBuildEndpointMatcher(builder, role)

Parameters:

builder – Name of the builder.
role – The role needed to get access to such endpoints.

StopBuildEndpointMatcher grants rights to stop builds.

class buildbot.www.authz.endpointmatchers.RebuildBuildEndpointMatcher(builder, role)

Parameters:

builder – Name of the builder.
role – The role needed to get access to such endpoints.

RebuildBuildEndpointMatcher grants rights to rebuild builds.

class buildbot.www.authz.endpointmatchers.EnableSchedulerEndpointMatcher(builder, role)

Parameters:

builder – Name of the builder.
role – The role needed to get access to such endpoints.

EnableSchedulerEndpointMatcher grants rights to enable and disable schedulers via the UI.

Role matchers

Role matchers are responsible for creating rules to match people and grant them roles. You can grant roles from groups information provided by the Auth plugins, or if you prefer directly to people’s email.

class buildbot.www.authz.roles.RolesFromGroups(groupPrefix)

Parameters:: groupPrefix – Prefix to remove from each group

RolesFromGroups grants roles from the groups of the user. If a user has group buildbot-admin, and groupPrefix is buildbot-, then user will be granted the role ‘admin’

ex:

roleMatchers=[
  util.RolesFromGroups(groupPrefix="buildbot-")
]

class buildbot.www.authz.roles.RolesFromEmails(roledict)

Parameters:: roledict – Dictionary with key=role, and value=list of email strings

RolesFromEmails grants roles to users according to the hardcoded emails.

ex:

roleMatchers=[
  util.RolesFromEmails(admins=["my@email.com"])
]

class buildbot.www.authz.roles.RolesFromDomain(roledict)

Parameters:: roledict – Dictionary with key=role, and value=list of domain strings

RolesFromDomain grants roles to users according to their email domains. If a user tried to login with email foo@gmail.com, then the user will be granted the role ‘admins’.

ex:

roleMatchers=[
  util.RolesFromDomain(admins=["gmail.com"])
]

class buildbot.www.authz.roles.RolesFromOwner(roledict)

Parameters:: roledict – Dictionary with key=role, and value=list of email strings

RolesFromOwner grants a given role when property owner matches the email of the user

ex:

roleMatchers=[
    RolesFromOwner(role="owner")
]

class buildbot.www.authz.roles.RolesFromUsername(roles, usernames)

Parameters:

roles – Roles to assign when the username matches.
usernames – List of usernames that have the roles.

RolesFromUsername grants the given roles when the username property is within the list of usernames.

ex:

roleMatchers=[
    RolesFromUsername(roles=["admins"], usernames=["root"]),
    RolesFromUsername(roles=["developers", "integrators"], usernames=["Alice", "Bob"])
]

Example Configs

Simple config which allows admin people to control everything, but allow anonymous to look at build results:

from buildbot.plugins import *
authz = util.Authz(
  allowRules=[
    util.AnyControlEndpointMatcher(role="admins"),
  ],
  roleMatchers=[
    util.RolesFromEmails(admins=["my@email.com"])
  ]
)
auth=util.UserPasswordAuth({'my@email.com': 'mypass'})
c['www']['auth'] = auth
c['www']['authz'] = authz

More complex config with separation per branch:

from buildbot.plugins import *

authz = util.Authz(
    stringsMatcher=util.fnmatchStrMatcher,  # simple matcher with '*' glob character
    # stringsMatcher = util.reStrMatcher,   # if you prefer regular expressions
    allowRules=[
        # admins can do anything,
        # defaultDeny=False: if user does not have the admin role, we continue parsing rules
        util.AnyEndpointMatcher(role="admins", defaultDeny=False),

        util.StopBuildEndpointMatcher(role="owner"),

        # *-try groups can start "try" builds
        util.ForceBuildEndpointMatcher(builder="try", role="*-try"),
        # *-mergers groups can start "merge" builds
        util.ForceBuildEndpointMatcher(builder="merge", role="*-mergers"),
        # *-releasers groups can start "release" builds
        util.ForceBuildEndpointMatcher(builder="release", role="*-releasers"),
        # if future Buildbot implement new control, we are safe with this last rule
        util.AnyControlEndpointMatcher(role="admins")
    ],
    roleMatchers=[
        RolesFromGroups(groupPrefix="buildbot-"),
        RolesFromEmails(admins=["homer@springfieldplant.com"],
                        reaper-try=["007@mi6.uk"]),
        # role owner is granted when property owner matches the email of the user
        RolesFromOwner(role="owner")
    ]
)
c['www']['authz'] = authz

Using GitHub authentication and allowing access to control endpoints for users in the “Buildbot” organization:

from buildbot.plugins import *
authz = util.Authz(
  allowRules=[
    util.AnyControlEndpointMatcher(role="BuildBot")
  ],
  roleMatchers=[
    util.RolesFromGroups()
  ]
)
auth=util.GitHubAuth('CLIENT_ID', 'CLIENT_SECRET')
c['www']['auth'] = auth
c['www']['authz'] = authz

2.5.17. Change Hooks

The /change_hook URL is a magic URL which will accept HTTP requests and translate them into changes for Buildbot. Implementations (such as a trivial json-based endpoint and a GitHub implementation) can be found in master/buildbot/www/hooks. The format of the URL is /change_hook/DIALECT where DIALECT is a package within the hooks directory. change_hook is disabled by default and each DIALECT has to be enabled separately, for security reasons.

An example www configuration line which enables change_hook and two DIALECTS:

c['www'] = {
    "change_hook_dialects": {
        'base': True,
        'somehook': {
            'option1': True,
            'option2':False
        },
    },
}

Within the www config dictionary arguments, the change_hook key enables/disables the module, and change_hook_dialects whitelists DIALECTs where the keys are the module names and the values are optional arguments which will be passed to the hooks.

The master/contrib/post_build_request.py script allows for the submission of an arbitrary change request. Run post_build_request.py --help for more information. The base dialect must be enabled for this to work.

2.5.17.1. Change Hooks Auth

By default, the change hook URL is not protected. Some hooks implement their own authentication method. Others require the generic method to be secured.

To protect URL against unauthorized access, you may use change_hook_auth option.

Note

This method uses HTTP BasicAuth. It implies the use of SSL via Reverse Proxy Configuration in order to be fully secured.

from twisted.cred import strcred
c['www'] = {
    ...,
    "change_hook_auth": [strcred.makeChecker("file:changehook.passwd")],
}

Create a file changehook.passwd with content:

user:password

change_hook_auth should be a list of ICredentialsChecker. See the details of available options in Twisted documentation.

Note

In the case of the "file:changehook.passwd" description in makeChecker, Buildbot checkconfig might give you a warning “not a valid file: changehook.passwd”. To resolve this, you need specify the full path to the file, f"file:{os.path.join(basedir, 'changehook.passwd')}".

2.5.17.2. Mercurial hook

The Mercurial hook uses the base dialect:

c['www'] = {
    ...,
    "change_hook_dialects": {'base': True},
}

Once this is configured on your buildmaster add the following hook on your server-side Mercurial repository’s hgrc:

[hooks]
changegroup.buildbot = python:/path/to/hgbuildbot.py:hook

You’ll find master/contrib/hgbuildbot.py, and its inline documentation, in the buildbot-contrib repository.

2.5.17.3. GitHub hook

Note

There is a standalone HTTP server available for receiving GitHub notifications as well: master/contrib/github_buildbot.py. This script may be useful in cases where you cannot expose the WebStatus for public consumption. Alternatively, you can setup a reverse proxy Reverse Proxy Configuration.

The GitHub hook has the following parameters:

secret (default None)

Secret token to use to validate payloads.

strict (default False)

If the hook must be strict regarding valid payloads. If the value is False (default), the signature will only be checked if a secret is specified and a signature was supplied with the payload. If the value is True, a secret must be provided, and payloads without signature will be ignored.

codebase (default None)

The codebase value to include with created changes. If the value is a function (or any other callable), it will be called with the GitHub event payload as argument and the function must return the codebase value to use for the event.

github_property_whitelist (default [])

A list of fnmatch expressions which match against the flattened pull request information JSON prefixed with github. For example github.number represents the pull request number. Available entries can be looked up in the GitHub API Documentation or by examining the data returned for a pull request by the API.

class (default None)

A class to be used for processing incoming payloads. If the value is None (default), the default class – buildbot.www.hooks.github.GitHubEventHandler – will be used. The default class handles ping, push and pull_request events only. If you’d like to handle other events (see Event Types & Payloads for more information), you’d need to subclass GitHubEventHandler and add handler methods for the corresponding events. For example, if you’d like to handle blah events, your code should look something like this:

from buildbot.www.hooks.github import GitHubEventHandler

class MyBlahHandler(GitHubEventHandler):

    def handle_blah(self, payload):
        # Do some magic here
        return [], 'git'

skips (default [r'\[ *skip *ci *\]', r'\[ *ci *skip *\]'])

A list of regex pattern makes buildbot ignore the push event. For instance, if user push 3 commits and the commit message of branch head contains a key string [ci skip], buildbot will ignore this push event.

If you want to disable the skip checking, please set it to [].

github_api_endpoint (default https://api.github.com)

If you have a self-host GitHub Enterprise installation, please set this URL properly.

token

If your GitHub or GitHub Enterprise instance does not allow anonymous communication, you need to provide an access token. Instructions can be found here.

pullrequest_ref (default merge)

Remote ref to test if a pull request is sent to the endpoint. See the GitHub developer manual for possible values for pull requests. (e.g. head)

The simplest way to use GitHub hook is as follows:

c['www'] = {
    "change_hook_dialects": {'github': {}},
}

Having added this line, you should add a webhook for your GitHub project (see Creating Webhooks page at GitHub). The parameters are:

Payload URL

This URL should point to /change_hook/github relative to the root of the web status. For example, if the base URL is http://builds.example.com/buildbot, then point GitHub to http://builds.example.com/buildbot/change_hook/github. To specify a project associated to the repository, append ?project=name to the URL.

Content Type

Specify application/x-www-form-urlencoded or application/json.

Secret

Any value. If you provide a non-empty value (recommended), make sure that your hook is configured to use it:

c['www'] = {
    ...,
    "change_hook_dialects": {
        'github': {
            'secret': 'MY-SECRET',
        },
    },
}

Which events would you like to trigger this webhook?

Click – Let me select individual events, then select Push and Pull request – other kind of events are not currently supported.

And then press the Add Webhook button.

Github hook creates 3 kinds of changes, distinguishable by their category field:

None: This change is a push to a branch.
Use util.ChangeFilter(category=None, repository="http://github.com/<org>/<project>")
'tag': This change is a push to a tag.
Use util.ChangeFilter(category='tag', repository="http://github.com/<org>/<project>")
'pull': This change is from a pull-request creation or update.
Use util.ChangeFilter(category='pull', repository="http://github.com/<org>/<project>"). In this case, the GitHub step must be used instead of the standard Git in order to be able to pull GitHub’s magic refs. With this method, the GitHub step will always checkout the branch merged with latest master. This allows to test the result of the merge instead of just the source branch. Note that you can use the GitHub for all categories of event.

Warning

Pull requests against every branch will trigger the webhook; the base branch name will be in the basename property of the build.

Warning

The incoming HTTP requests for this hook are not authenticated by default. Anyone who can access the web server can “fake” a request from GitHub, potentially causing the buildmaster to run arbitrary code.

To protect URL against unauthorized access you should use Change Hooks Auth option. Then change the Payload URL of your GitHub webhook to https://user:password@builds.example.com/bbot/change_hook/github.

2.5.17.4. BitBucket hook

The BitBucket hook is as simple as the GitHub one and takes no options.

c['www'] = {
    ...,
    "change_hook_dialects": {'bitbucket': True},
}

When this is set up, you should add a POST service pointing to /change_hook/bitbucket relative to the root of the web status. For example, if the grid URL is http://builds.example.com/bbot/grid, then point BitBucket to http://builds.example.com/change_hook/bitbucket. To specify a project associated to the repository, append ?project=name to the URL.

Note that there is a standalone HTTP server available for receiving BitBucket notifications, as well: master/contrib/bitbucket_buildbot.py. This script may be useful in cases where you cannot expose the WebStatus for public consumption.

Warning

As in the previous case, the incoming HTTP requests for this hook are not authenticated by default. Anyone who can access the web status can “fake” a request from BitBucket, potentially causing the buildmaster to run arbitrary code.

To protect URL against unauthorized access you should use Change Hooks Auth option. Then, create a BitBucket service hook (see https://confluence.atlassian.com/display/BITBUCKET/POST+Service+Management) with a WebHook URL like https://user:password@builds.example.com/bbot/change_hook/bitbucket.

Note that as before, not using change_hook_auth can expose you to security risks.

2.5.17.5. Bitbucket Cloud hook

c['www'] = {
    ...,
    "change_hook_dialects": {'bitbucketcloud': {}},
}

When this is set up, you should add a webhook pointing to /change_hook/bitbucketcloud relative to the root of the web status.

According to the type of the event, the change category is set to push, pull-created, pull-rejected, pull-updated, pull-fulfilled or ref-deleted.

The Bitbucket Cloud hook may have the following optional parameters:

codebase (default None): The codebase value to include with changes or a callable object that will be passed the payload in order to get it.
bitbucket_property_whitelist (default []): A list of fnmatch expressions which match against the flattened pull request information JSON prefixed with bitbucket. For example bitbucket.id represents the pull request ID. Available entries can be looked up in the BitBucket API Documentation or by examining the data returned for a pull request by the API.

Warning

The incoming HTTP requests for this hook are not authenticated by default. Anyone who can access the web server can “fake” a request from Bitbucket Cloud, potentially causing the buildmaster to run arbitrary code.

2.5.17.6. Bitbucket Server hook

c['www'] = {
    ...,
    "change_hook_dialects": {'bitbucketserver': {}},
}

When this is set up, you should add a webhook pointing to /change_hook/bitbucketserver relative to the root of the web status.

According to the type of the event, the change category is set to push, pull-created, pull-rejected, pull-updated, pull-fulfilled or ref-deleted.

The Bitbucket Server hook may have the following optional parameters:

codebase (default None): The codebase value to include with changes or a callable object that will be passed the payload in order to get it.
bitbucket_property_whitelist (default []): A list of fnmatch expressions which match against the flattened pull request information JSON prefixed with bitbucket. For example bitbucket.id represents the pull request ID. Available entries can be looked up in the BitBucket API Documentation or by examining the data returned for a pull request by the API.

Warning

The incoming HTTP requests for this hook are not authenticated by default. Anyone who can access the web server can “fake” a request from Bitbucket Server, potentially causing the buildmaster to run arbitrary code.

Note

This hook requires the bitbucket-webhooks plugin (see https://marketplace.atlassian.com/plugins/nl.topicus.bitbucket.bitbucket-webhooks/server/overview).

2.5.17.7. Poller hook

The poller hook allows you to use GET or POST requests to trigger polling. One advantage of this is your buildbot instance can poll at launch (using the pollAtLaunch flag) to get changes that happened while it was down, but then you can still use a commit hook to get fast notification of new changes.

Suppose you have a poller configured like this:

c['change_source'] = SVNPoller(
    repourl="https://amanda.svn.sourceforge.net/svnroot/amanda/amanda",
    split_file=split_file_branches,
    pollInterval=24*60*60,
    pollAtLaunch=True,
)

And you configure your WebStatus to enable this hook:

c['www'] = {
    ...,
    "change_hook_dialects": {'poller': True},
}

Then you will be able to trigger a poll of the SVN repository by poking the /change_hook/poller URL from a commit hook like this:

curl -s -F poller=https://amanda.svn.sourceforge.net/svnroot/amanda/amanda \
    http://yourbuildbot/change_hook/poller

If no poller argument is provided then the hook will trigger polling of all polling change sources.

You can restrict which pollers the webhook has access to using the allowed option:

c['www'] = {
    ...,
    'change_hook_dialects': {
        'poller': {
            'allowed': ['https://amanda.svn.sourceforge.net/svnroot/amanda/amanda']
        }
    }
}

2.5.17.8. GitLab hook

c['www'] = {
    ...,
    "change_hook_dialects": {
        'gitlab' : {
            'secret': '...',
        },
    },
}

The GitLab hook has the following parameters:

secret (default None): Secret token to use to validate payloads.

When this is set up, you should add a POST service pointing to /change_hook/gitlab relative to the root of the web status. For example, if the grid URL is http://builds.example.com/bbot/grid, then point GitLab to http://builds.example.com/change_hook/gitlab. The project and/or codebase can also be passed in the URL by appending ?project=name or ?codebase=foo to the URL. These parameters will be passed along to the scheduler.

Note

To handle merge requests from forks properly, it’s easiest to use a GitLab source step rather than a Git source step.

Note

Your Git or GitLab step must be configured with a git@ repourl, not a https: one, else the change from the webhook will not trigger a build.

Warning

As in the previous case, the incoming HTTP requests for this hook are not authenticated by default. Anyone who can access the web status can “fake” a request from your GitLab server, potentially causing the buildmaster to run arbitrary code.

Warning

When applicable, you need to permit access to internal/local networks. See https://docs.gitlab.com/ee/security/webhooks.html for details.

To protect URL against unauthorized access you should either

set secret token in the configuration above, then set it in the GitLab service hook declaration, or

use the Change Hooks Auth option. Then, create a GitLab service hook (see https://your.gitlab.server/help/web_hooks) with a WebHook URL like https://user:password@builds.example.com/bbot/change_hook/gitlab.

Note that as before, not using change_hook_auth can expose you to security risks.

2.5.17.9. Gitorious Hook

The Gitorious hook is as simple as GitHub one and it also takes no options.

c['www'] = {
    ...,
    "change_hook_dialects": {'gitorious': True},
}

When this is set up, you should add a POST service pointing to /change_hook/gitorious relative to the root of the web status. For example, if the grid URL is http://builds.example.com/bbot/grid, then point Gitorious to http://builds.example.com/change_hook/gitorious.

Warning

As in the previous case, the incoming HTTP requests for this hook are not authenticated by default. Anyone who can access the web status can “fake” a request from your Gitorious server, potentially causing the buildmaster to run arbitrary code.

To protect URL against unauthorized access you should use Change Hooks Auth option. Then, create a Gitorious web hook with a WebHook URL like https://user:password@builds.example.com/bbot/change_hook/gitorious.

Note that as before, not using change_hook_auth can expose you to security risks.

Note

Web hooks are only available for local Gitorious installations, since this feature is not offered as part of Gitorious.org yet.

2.5.17.10. Custom Hooks

Custom hooks are supported via the Plugin Infrastructure in Buildbot mechanism. You can subclass any of the available hook handler classes available in buildbot.www.hooks and register it in the plugin system via a custom python module. For convenience, you can also use the generic option custom_class, e.g.:

from buildbot.plugins import webhooks
class CustomBase(webhooks.base):
    def getChanges(self, request):
        args = request.args
        chdict = {
            "revision": args.get(b'revision'),
            "repository": args.get(b'repository'),
            "project": args.get(b'project'),
            "codebase": args.get(b'codebase')
        }
        return ([chdict], None)

c['www'] = {
    ...,
    "change_hook_dialects": {
        'base' : {
            'custom_class': CustomBase,
        },
    },
}

2.5.18. Custom Services

2.5.18.1. FailingBuildsetCanceller

class buildbot.plugins.util.FailingBuildsetCanceller

The purpose of this service is to cancel builds once one build on a buildset fails.

This is useful for reducing use of resources in cases when there is no need to gather information from all builds of a buildset once one of them fails.

The service may be configured to track a subset of builds. This is controlled by the filters parameter. The decision on whether to cancel a build is done once a build fails.

The following parameters are supported by the FailingBuildsetCanceller:

name: (required, a string) The name of the service. All services must have different names in Buildbot. For most use cases value like buildset_canceller will work fine.
filters: (required, a list of three-element tuples) The source stamp filters that specify which builds the build canceller should track. The first element of each tuple must be a list of builder names that the filter would apply to. The second element of each tuple must be a list of builder names that will have the builders cancelled once a build fails. Alternatively, the value None as the second element of the tuple specifies that all builds should be cancelled. The third element of each tuple must be an instance of buildbot.util.SourceStampFilter.

2.5.18.2. OldBuildCanceller

class buildbot.plugins.util.OldBuildCanceller

The purpose of this service is to cancel builds on branches as soon as a superseding build request is created from a new commit on the branch.

This allows to reduce resource usage in projects that use Buildbot to run tests on pull request branches. For example, if a developer pushes new commits to the branch, notices and fixes a problem quickly and then pushes again, the builds that have been started on the older commit will be cancelled immediately instead of waiting for builds to finish.

The service may be configured to track a subset of builds. This is controlled by the filters parameter. The decision on whether to track a build is done on build startup. Configuration changes are ignored for builds that have already started.

Certain version control systems have multiple branch names that map to a single logical branch which makes OldBuildCanceller unable to cancel builds even in the presence of new commits. The handling of such scenarios is controlled by branch_key.

The following parameters are supported by the OldBuildCanceller:

name

(required, a string) The name of the service. All services must have different names in Buildbot. For most use cases value like build_canceller will work fine.

filters

(required, a list of two-element tuples) The source stamp filters that specify which builds the build canceller should track. The first element of each tuple must be a list of builder names that the filter would apply to. The second element of each tuple must be an instance of buildbot.util.SourceStampFilter.

branch_key

(optional, a function that receives source stamp or change dictionary and returns a string) Allows customizing the branch that is used to track builds and decide whether to cancel them. The function receives a dictionary with at least the following keys: project, codebase, repository, branch and must return a string.

The default implementation implements custom handling for the following Version control systems:

Gerrit: branches that identify changes (use format refs/changes/*/*/*) have the change iteration number removed.

Pass lambda ss: ss['branch'] to always use branch property directly.

Note that OldBuildCanceller will only cancel builds with the same project, codebase, repository tuple as incoming change, so these do not need to be taken into account by this function.

Custom services are stateful components of Buildbot that can be added to the services key of the Buildbot config dictionary. The following is the services that are meant to be used without advanced knowledge of Buildbot.

FailingBuildsetCanceller

OldBuildCanceller

More complex services are described in the developer section of the Buildbot manual. They are meant to be used by advanced users of Buildbot.

2.5.19. DbConfig

DbConfig is a utility for master.cfg to get easy-to-use key-value storage in the Buildbot database.

DbConfig can get and store any json-able object to the db for use by other masters or separate UI plugins to edit them.

The design is intentionally simplistic, as the focus is on ease of use rather than efficiency. A separate db connection is created each time get() or set() is called.

Example:

from buildbot.plugins import util, worker

c = BuildmasterConfig = {}
c['db_url'] = 'mysql://username:password@mysqlserver/buildbot'
dbConfig = util.DbConfig(BuildmasterConfig, basedir)
workers = dbConfig.get("workers")
c['workers'] = [
    worker.Worker(worker['name'], worker['passwd'],
                  properties=worker.get('properties')),
    for worker in workers
]

class DbConfig

__init__(BuildmasterConfig, basedir)

Parameters:

BuildmasterConfig – the BuildmasterConfig, where db_url is already configured
basedir – basedir global variable of the master.cfg run environment. SQLite urls are relative to this dir

get(name, default=MarkerClass)

Parameters:

name – the name of the config variable to retrieve
default – in case the config variable has not been set yet, default is returned if defined, else KeyError is raised

set(name, value)

Parameters:

name – the name of the config variable to be set
value – the value of the config variable to be set

2.5.20. Configurators

For advanced users or plugin writers, the configurators key is available and holds a list of buildbot.interfaces.IConfigurator. The configurators will run after the master.cfg has been processed, and will modify the config dictionary. Configurator implementers should make sure that they are interoperable with each other, which means carefully modifying the config to avoid overriding a setting already made by the user or another configurator. Configurators are run (thus prioritized) in the order of the configurators list.

2.5.20.1. JanitorConfigurator

Buildbot stores historical information in its database. In a large installation, these can quickly consume disk space, yet developers never consult this historical information in many cases.

JanitorConfigurator creates a builder and Nightly scheduler which will regularly remove old information. At the moment, it only supports cleaning of logs, but it will contain more features as we implement them.

from buildbot.plugins import util
from datetime import timedelta

# configure a janitor which will delete all logs older than one month,
# and will run on sundays at noon
c['configurators'] = [util.JanitorConfigurator(
    logHorizon=timedelta(weeks=4),
    hour=12,
    dayOfWeek=6
)]

Parameters for JanitorConfigurator are:

logHorizon: A timedelta object describing the minimum time for which the log data should be maintained.
hour, dayOfWeek, …: Arguments given to the Nightly scheduler which is backing the JanitorConfigurator. Determines when the cleanup will be done. With this, you can configure it daily, weekly or even hourly if you wish. You probably want to schedule it when Buildbot is less loaded.

2.5.21. Manhole

Manhole is an interactive Python shell that gives full access to the Buildbot master instance. It is probably only useful for Buildbot developers.

Using Manhole requires the cryptography and pyasn1 python packages to be installed. These are not part of the normal Buildbot dependencies.

There are several implementations of Manhole available, which differ by the authentication mechanisms and the security of the connection.

Note

Manhole exposes full access to the buildmaster’s account (including the ability to modify and delete files). It’s recommended not to expose the manhole to the Internet and to use a strong password.

class buildbot.plugins.util.AuthorizedKeysManhole(port, keyfile, ssh_hostkey_dir)

A manhole implementation that accepts encrypted ssh connections and authenticates by ssh keys. The prospective client must have an ssh private key that matches one of the public keys in manhole’s authorized keys file.

Parameters:

port (string or int) – The port to listen on. This is a strports specification string, like tcp:12345 or tcp:12345:interface=127.0.0.1. Bare integers are treated as a simple tcp port.
keyfile (string) – The path to the file containing public parts of the authorized SSH keys. The path is interpreted relative to the buildmaster’s basedir. The file should contain one public SSH key per line. This is the exact same format as used by sshd in ~/.ssh/authorized_keys.
ssh_hostkey_dir (string) – The path to the directory which contains ssh host keys for this server.

class buildbot.plugins.util.PasswordManhole(port, username, password, ssh_hostkey_dir)

A manhole implementation that accepts encrypted ssh connections and authenticates by username and password.

Parameters:

port (string or int) – The port to listen on. This is a strports specification string, like tcp:12345 or tcp:12345:interface=127.0.0.1. Bare integers are treated as a simple tcp port.
username (string) – The username to authenticate.
password (string) – The password of the user to authenticate.
ssh_hostkey_dir (string) – The path to the directory which contains ssh host keys for this server.

class buildbot.plugins.util.TelnetManhole(port, username, password)

A manhole implementation that accepts unencrypted telnet connections and authenticates by username and password.

Note

This connection method is not secure and should not be used anywhere where the port is exposed to the Internet.

Parameters:

port (string or int) – The port to listen on. This is a strports specification string, like tcp:12345 or tcp:12345:interface=127.0.0.1. Bare integers are treated as a simple tcp port.
username (string) – The username to authenticate.
password (string) – The password of the user to authenticate.

2.5.21.1. Using manhole

The interactive Python shell can be entered by simply connecting to the host in question. For instance, in the case of ssh password-based manhole, the configuration may look like this:

from buildbot import manhole
c['manhole'] = manhole.PasswordManhole("tcp:1234:interface=127.0.0.1",
                                       "admin", "passwd",
                                       ssh_hostkey_dir="data/ssh_host_keys")

The above ssh_hostkey_dir declares a path relative to the buildmaster’s basedir to look for ssh keys. To create an ssh key, navigate to the buildmaster’s basedir and run:

mkdir -p data/ssh_host_keys
ckeygen3 -t rsa -f "data/ssh_host_keys/ssh_host_rsa_key"

Restart Buildbot and then try to connect to the running buildmaster like this:

ssh -p1234 admin@127.0.0.1
# enter passwd at prompt

After connection has been established, objects can be explored in more depth using dir(x) or the helper function show(x). For example:

>>> master.workers.workers
{'example-worker': <Worker 'example-worker', current builders: runtests>}

>>> show(master)
data attributes of <buildbot.master.BuildMaster instance at 0x7f7a4ab7df38>
                       basedir : '/home/dustin/code/buildbot/t/buildbot/'...
                     botmaster : <type 'instance'>
                buildCacheSize : None
                  buildHorizon : None
                   buildbotURL : http://localhost:8010/
               changeCacheSize : None
                    change_svc : <type 'instance'>
                configFileName : master.cfg
                            db : <class 'buildbot.db.connector.DBConnector'>
                        db_url : sqlite:///state.sqlite
                              ...
>>> show(master.botmaster.builders['win32'])
data attributes of <Builder ''builder'' at 48963528>

The buildmaster’s SSH server will use a different host key than the normal sshd running on a typical unix host. This will cause the ssh client to complain about a host key mismatch, because it does not realize there are two separate servers running on the same host. To avoid this, use a clause like the following in your .ssh/config file:

Host remotehost-buildbot
HostName remotehost
HostKeyAlias remotehost-buildbot
Port 1234
# use 'user' if you use PasswordManhole and your name is not 'admin'.
# if you use AuthorizedKeysManhole, this probably doesn't matter.
User admin

2.5.22. Multimaster

Warning

Buildbot Multimaster is considered experimental. There are still some companies using it in production. Don’t hesitate to use the mailing lists to share your experience.

Buildbot supports interconnection of several masters. This has to be done through a multi-master enabled message queue backend. As of now the only one supported is wamp and crossbar.io. see wamp

There are then several strategy for introducing multimaster in your buildbot infra. A simple way to say it is by adding the concept of symmetrics and asymmetrics multimaster (like there is SMP and AMP for multi core CPUs)

Symmetric multimaster is when each master share the exact same configuration. They run the same builders, same schedulers, same everything, the only difference is that workers are connected evenly between the masters (by any means (e.g. DNS load balancing, etc)) Symmetric multimaster is good to use to scale buildbot horizontally.

Asymmetric multimaster is when each master have different configuration. Each master may have a specific responsibility (e.g schedulers, set of builder, UI). This was more how you did in 0.8, also because of its own technical limitations. A nice feature of asymmetric multimaster is that you can have the UI only handled by some masters.

Separating the UI from the controlling will greatly help in the performance of the UI, because badly written BuildSteps?? can stall the reactor for several seconds.

The fanciest configuration would probably be a symmetric configuration for everything but the UI. You would scale the number of UI master according to your number of UI users, and scale the number of engine masters to the number of workers.

Depending on your workload and size of master host, it is probably a good idea to start thinking of multimaster starting from a hundred workers connected.

Multimaster can also be used for high availability, and seamless upgrade of configuration code. Complex configuration indeed requires sometimes to restart the master to reload custom steps or code, or just to upgrade the upstream buildbot version.

In this case, you will implement following procedure:

Start new master(s) with new code and configuration.
Send a graceful shutdown to the old master(s).
New master(s) will start taking the new jobs, while old master(s) will just finish managing the running builds.
As an old master is finishing the running builds, it will drop the connections from the workers, who will then reconnect automatically, and by the mean of load balancer will get connected to a new master to run new jobs.

As buildbot nine has been designed to allow such procedure, it has not been implemented in production yet as we know. There is probably a new REST API needed in order to gracefully shutdown a master, and the details of gracefully dropping the connection to the workers to be sorted out.

2.5.23. Multiple-Codebase Builds

What if an end-product is composed of code from several codebases? Changes may arrive from different repositories within the tree-stable-timer period. Buildbot will not only use the source-trees that contain changes but also needs the remaining source-trees to build the complete product.

For this reason, a Scheduler can be configured to base a build on a set of several source-trees that can (partly) be overridden by the information from incoming Changes.

As described in Source-Stamps, the source for each codebase is identified by a source stamp, containing its repository, branch and revision. A full build set will specify a source stamp set describing the source to use for each codebase.

Configuring all of this takes a coordinated approach. A complete multiple repository configuration consists of:

a codebase generator

Every relevant change arriving from a VC must contain a codebase. This is done by a codebaseGenerator that is defined in the configuration. Most generators examine the repository of a change to determine its codebase, using project-specific rules.

some schedulers

Each scheduler has to be configured with a set of all required codebases to build a product. These codebases indicate the set of required source-trees. In order for the scheduler to be able to produce a complete set for each build, the configuration can give a default repository, branch, and revision for each codebase. When a scheduler must generate a source stamp for a codebase that has received no changes, it applies these default values.

multiple source steps - one for each codebase

A Builder’s build factory must include a source step for each codebase. Each of the source steps has a codebase attribute which is used to select an appropriate source stamp from the source stamp set for a build. This information comes from the arrived changes or from the scheduler’s configured default values.

Note

Each source step has to have its own workdir set in order for the checkout to be done for each codebase in its own directory.

Note

Ensure you specify the codebase within your source step’s Interpolate() calls (e.g. http://.../svn/%(src:codebase:branch)s). See Interpolate for details.

Warning

Defining a codebaseGenerator that returns non-empty (not '') codebases will change the behavior of all the schedulers.

2.5.24. Miscellaneous Configuration

2.5.24.1. SourceStampFilter

class buildbot.util.SourceStampFilter

This class is used to filter source stamps. It is conceptually very similar to ChangeFilter except that it operates on source stamps. It accepts a set of conditions. A source stamp is considered accepted if all conditions are satisfied. The conditions are specified via the constructor arguments.

The following parameters are supported by the SourceStampFilter:

project_eq, codebase_eq, repository_eq, branch_eq

(optional, a string or a list of strings) The corresponding property of the source stamp must match exactly to at least one string from the value supplied by the argument.

branch uses util.NotABranch as its default value which indicates that no checking should be done, because the branch may actually have None value to be checked.

project_not_eq, codebase_not_eq, repository_not_eq, branch_not_eq

(optional, a string or a list of strings) The corresponding property of the source stamp must not match exactly to any string from the value supplied by the argument.

project_re, codebase_re, repository_re, branch_re

(optional, a string or a list of strings or regex pattern objects) The corresponding property of the source stamp must match to at least one regex from the value supplied by the argument. Any strings passed via this parameter are converted to a regex via re.compile.

project_not_re, codebase_not_re, repository_not_re, branch_not_re

(optional, a string or a list of strings or regex pattern objects) The corresponding property of the source stamp must not match to any regex from the value supplied by the argument. Any strings passed via this parameter are converted to a regex via re.compile.

filter_fn

(optional, a callable accepting a dictionary and returning a boolean) The given function will be passed the source stamp. It is expected to return True if the source stamp is matched, False otherwise. In case of a match, all other conditions will still be evaluated.

2.5.24.2. ChangeFilter

class buildbot.util.ChangeFilter

This class is used to filter changes. It is conceptually very similar to SourceStampFilter except that it operates on changes. The class accepts a set of conditions. A change is considered acepted if all conditions are satisfied. The conditions are specified via the constructor arguments.

The following parameters are supported by the ChangeFilter:

project, repository, branch, category, codebase

(optional, a string or a list of strings) The corresponding attribute of the change must match exactly to at least one string from the value supplied by the argument.

branch uses util.NotABranch as its default value which indicates that no checking should be done, because the branch may actually have None value to be checked.

project_not_eq, repository_not_eq, branch_not_eq, category_not_eq, codebase_not_eq

(optional, a string or a list of strings) The corresponding attribute of the change must not match exactly to any of the strings from the value supplied by the argument.

branch uses util.NotABranch as its default value which indicates that no checking should be done, because the branch may actually have None value to be checked.

project_re, repository_re, branch_re, category_re, codebase_re

(optional, a string or a list of strings or regex pattern objects) The corresponding attribute of the change must match to at least one regex from the value supplied by the argument. Any strings passed via this parameter are converted to a regex via re.compile.

project_not_re, repository_not_re, branch_not_re, category_not_re, codebase_not_re

(optional, a string or a list of strings or regex pattern objects) The corresponding attribute of the change must not match to at least any regex from the value supplied by the argument. Any strings passed via this parameter are converted to a regex via re.compile.

property_eq

(optional, a dictionary containing string keys and values each of which with a string or a list of strings) The property of the change with corresponding name must match exactly to at least one string from the value supplied by the argument.

property_not_eq

(optional, a string or a list of strings) The property of the change with corresponding name must not be present or not match exactly to at least one string from the value supplied by the argument.

property_re

(optional, a string or a list of strings or regex pattern objects) The property of the change with corresponding name must match to at least one regex from the value supplied by the argument. Any strings passed via this parameter are converted to a regex via re.compile.

property_not_re

(optional, a string or a list of strings or regex pattern objects) The property of the change with corresponding name must not be present or not match to at least one regex from the value supplied by the argument. Any strings passed via this parameter are converted to a regex via re.compile.

project_fn, repository_fn, branch_fn, category_fn, codebase_fn

(optional, a callable accepting a string and returning a boolean) The given function will be passed the value from the change that corresponds to the parameter name. It is expected to return True if the change is matched, False otherwise. In case of a match, all other conditions will still be evaluated.

filter_fn

(optional, a callable accepting a Change object and returning a boolean) The given function will be passed the change. It is expected to return True if the change is matched, False otherwise. In case of a match, all other conditions will still be evaluated.

Secrets in conditions

ChangeFilter does not support renderables. Accordingly, secrets cannot be used to construct the conditions that will later be used to filter changes.

This does not reduce security of the system because in order for secret values to be useful for filtering, they will need to be present in the changes themselves. The change information is stored in the database and frequently appears in the logs.

Best practice is to make sure secret values are not encoded in changes such as in repository URLs. Most of the source steps support passing authentication information separately from repository URL.

If encoding secrets is unavoidable, then changes should be filtered using regex (e.g. via repository_re argument) or custom callback functions (e.g. via repository_fn or filter_fn arguments).

Examples

ChangeFilter can be setup like this:

from buildbot.plugins import util
my_filter = util.ChangeFilter(project_re="^baseproduct/.*", branch="devel")

and then assigned to a scheduler with the change_filter parameter:

sch = SomeSchedulerClass(..., change_filter=my_filter)

buildbot.www.hooks.github.GitHubEventHandler has a special github_distinct property that can be used to specify whether or not non-distinct changes should be considered. For example, if a commit is pushed to a branch that is not being watched and then later pushed to a watched branch, by default, this will be recorded as two separate changes. In order to record a change only the first time the commit appears, you can use a custom ChangeFilter like this:

ChangeFilter(filter_fn=lambda c: c.properties.getProperty('github_distinct'))

For anything more complicated, a Python function can be defined to recognize the wanted strings:

def my_branch_fn(branch):
    return branch in branches_to_build and branch not in branches_to_ignore
my_filter = util.ChangeFilter(branch_fn=my_branch_fn)

This section outlines miscellaneous functionality that is useful for configuration but does not fit any other section.

2.5.25. Testing Utilities

2.5.25.1. Worker command expectations

TestBuildStepMixin is used to test steps and accepts command expectations to its expect_commands method. These command expectations are instances of classes listed in this page.

In all cases the arguments used to construct the expectation is what is expected to receive from the step under test. The methods called on the command are used to build a list of effects that the step will observe.

class buildbot.test.steps.Expect

This class is the base class of all command expectation classes. It must not be instantiated by the user. It provides methods that are common to all command expectations.

exit(code)

Parameters:: code (int) – Exit code

Specifies command exit code sent to the step. In most cases 0 signify success, other values signify failure.

stdout(output)

Parameters:: output – stdout output to send to the step. Must be an instance of bytes or str.

Specifies stdout stream in the stdio log that is sent by the command to the step.

stderr(output)

Parameters:: output – stderr output to send to the step. Must be an instance of bytes or str.

Specifies stderr stream in the stdio log that is sent by the command to the step.

log(name, **streams)

Parameters:

name (str) – The name of the log.
streams (kwargs) – The log streams of the log streams. The most common are stdout and stderr. The values must be instances of bytes or str.

Specifies logs sent by the command to the step.

For stdio log and stdout stream use the stdout() function.

For stdio log and stderr stream use the stderr() function.

error(error)

Parameters:: error – An instance of an exception to throw when running the command.

Throws an exception when running the command. This is often used to simulate broken connection by throwing in an instance of twisted.internet.error.ConnectionLost.

ExpectShell

class buildbot.test.steps.ExpectShell(Expect)

This class represents a shell command sent to the worker.

Usually the stdout log produced by the command is specified by the .stdout method, the stderr log is specified by the .stderr method and the exit code is specified by the .exit method.

ExpectShell(workdir='myworkdir', command=["my-test-command", "arg1", "arg2"])
.stdout(b'my sample output')
.exit(0)

__init__(workdir, command, env=None, want_stdout=1, want_stderr=1, initial_stdin=None, timeout=20 * 60, max_time=None, sigterm_time=None, logfiles=None, use_pty=None, log_environ=True, interrupt_signal=None): Initializes the expectation.

ExpectStat

class buildbot.test.steps.ExpectStat(Expect)

This class represents a stat command sent to the worker.

Tests usually indicate the existence of the file by calling the .exit method.

__init__(file, workdir=None, log_environ=None): Initializes the expectation.

stat(mode, inode=99, dev=99, nlink=1, uid=0, gid=0, size=99, atime=0, mtime=0, ctime=0)

Specifies os.stat result that is sent back to the step.

In most cases it’s more convenient to use stat_file or stat_dir.

stat_file(mode=0, size=99, atime=0, mtime=0, ctime=0)

Parameters:: mode (int) – Additional mode bits to set

Specifies os.stat result of a regular file.

stat_dir(mode=0, size=99, atime=0, mtime=0, ctime=0)

Parameters:: mode (int) – Additional mode bits to set

Specifies os.stat result of a directory.

ExpectUploadFile

class buildbot.test.steps.ExpectUploadFile(Expect)

This class represents a uploadFile command sent to the worker.

__init__(blocksize=None, maxsize=None, workersrc=None, workdir=None, writer=None, keepstamp=None, slavesrc=None, interrupted=False): Initializes the expectation.

upload_string(string, error=None)

Parameters:

string (str) – The data of the file to sent to the step.
error (object) – An optional instance of an exception to raise to simulate failure to transfer data.

Specifies the data to send to the step.

ExpectDownloadFile

class buildbot.test.steps.ExpectDownloadFile(Expect)

This class represents a downloadFile command sent to the worker. Tests usually check what the step attempts to send to the worker by calling .download_string and checking what data the supplied callable receives.

__init__(blocksize=None, maxsize=None, workerdest=None, workdir=None, reader=None, mode=None, interrupted=False, slavesrc=None, slavedest=None): Initializes the expectation.

download_string(dest_callable, size=1000)

Parameters:

dest_callable (callable) – A callable to call with the data that is being sent from the step.
size (int) – The size of the data to read

Specifies the callable to store the data that the step wants the worker to download.

ExpectMkdir

class buildbot.test.steps.ExpectMkdir(Expect)

This class represents a mkdir command sent to the worker.

__init__(dir=None, log_environ=None)): Initializes the expectation.

ExpectRmdir

class buildbot.test.steps.ExpectRmdir(Expect)

This class represents a rmdir command sent to the worker.

__init__(dir=None, log_environ=None, timeout=None, path=None): Initializes the expectation.

ExpectCpdir

class buildbot.test.steps.ExpectCpdir(Expect)

This class represents a cpdir command sent to the worker.

__init__(fromdir=None, todir=None, log_environ=None, timeout=None, max_time=None): Initializes the expectation.

ExpectRmfile

class buildbot.test.steps.ExpectRmfile(Expect)

This class represents a rmfile command sent to the worker.

__init__(path=None, log_environ=None): Initializes the expectation.

ExpectGlob

class buildbot.test.steps.ExpectGlob(Expect)

This class represents a mkdir command sent to the worker.

__init__(path=None, log_environ=None): Initializes the expectation.

files(files=None)

Parameters:: files (list) – An optional list of returned files.

Specifies the list of files returned to the step.

ExpectListdir

class buildbot.test.steps.ExpectListdir(Expect)

This class represents a mkdir command sent to the worker.

__init__(dir=None):: Initializes the expectation.

files(files=None)

Parameters:: files (list) – An optional list of returned files.

Specifies the list of files returned to the step.

2.5.25.2. TestReactorMixin

class buildbot.test.reactor.TestReactorMixin

The class TestReactorMixin is used to create a fake twisted.internet.reactor in tests. This allows to mock the flow of time in tests. The fake reactor becomes available as self.reactor in the test case that mixes in TestReactorMixin.

Call self.reactor.advance(seconds) to advance the mocked time by the specified number of seconds.

Call self.reactor.pump(seconds_list) to advance the mocked time multiple times as if by calling advance.

For more information see the documentation of twisted.internet.task.Clock.

setup_test_reactor(use_asyncio=False)

:param bool use_asyncio Whether to enable asyncio integration.

Call this function in the setUp() of the test case to setup fake reactor.

2.5.25.3. TestBuildStepMixin

class buildbot.test.steps.TestBuildStepMixin

The class TestBuildStepMixin allows to test build steps. It mocks the connection to the worker. The commands sent to the worker can be verified and command results can be injected back into the step under test. Additionally, the step under test is modified to allow checking how the step runs and what results it produces.

The following is an example of a basic step test:

class RemovePYCs(TestBuildStepMixin, TestReactorMixin, unittest.TestCase):

    def setUp(self):
        self.setup_test_reactor()
        return self.setup_test_build_step()

    def tearDown(self):
        return self.tear_down_test_build_step()

    @defer.inlineCallbacks
    def test_run_ok(self):
        self.setup_step(python_twisted.RemovePYCs())
        self.expect_commands(
            ExpectShell(workdir='wkdir',
                        command=['find', '.', '-name', '\'*.pyc\'', '-exec', 'rm', '{}', ';'])
            .exit(0)
        )
        self.expect_outcome(result=SUCCESS, state_string='remove .pycs')
        return self.run_step()

Basic workflow is as follows:

The test case must derive from TestReactorMixin and properly setup it.

In setUp() of test case call self.setup_test_build_step().

In unit test call self.setup_step(step) which will setup the step for testing.

Call self.expect_commands(commands) to specify commands that the step is expected to run and the results of these commands.

Call various other expect_* member functions to define other expectations.

Call self.run_step() to actually run the step.

All expectations are verified once the step has completed running.

setup_test_build_step(): Call this function in the setUp() method of the test case to setup step testing machinery.

tear_down_test_build_step(): Call this function in the tearDown() of the test case to destroy step testing machinery.

setup_step(step, worker_env=None, build_files=None)

Parameters:

worker_env (dict) – An optional dictionary of environment variables on the mock worker.
build_files (list) – An optional list of source files that were changed in the build.

Returns:

An instance of prepared step (not the same as the step argument).

Prepares the given step for testing. The method mimics how Buildbot instantiates steps in reality and thus the step parameter is used only as a factory for creating the real step.

step: The step under test. This attribute is available after setup_step() is run.

expect_commands(*commands)

Parameters:: commands – A list of commands that are expected to be run (a subclass of buildbot.test.steps.Expect).

Sets up an expectation of step sending the given commands to worker.

expect_outcome(result, state_string=None)

Parameters:

result – A result from buildbot.process.results.
state_string (str) – An optional status text.

Sets up an expectation of the step result.

expect_property(property, value, source=None)

Parameters:

property (str) – The name of the property
value (str) – The value of the property
source (str) – An optional source of the property

Sets up an expectation of a property set by the step

expect_no_property(self, property)

Parameters:: property (str) – The name of the property

Sets up an expectation of an absence of a property set by the step.

expect_log_file(self, logfile, contents)

Parameters:

logfile (str) – The name of the log file
contents (str) – The contents of the log file

Sets up an expectation of a log file being produced by the step. Only the stdout associated with the log file is checked. To check the stderr see expect_log_file_stderr()

expect_log_file_stderr(self, logfile, contents)

Parameters:

logfile (str) – The name of the log file
contents (str) – The contents of the log file

Sets up an expectation of a stderr output in log file being produced by the step.

expect_build_data(name, value, source)

Parameters:

name (str) – The name of the build data.
value (str) – The value of the build data.
source (str) – The source of the build data.

Sets up an expectation of build data produced by the step.

expect_hidden(hidden=True)

Parameters:: hidden (bool) – Whether the step should be hidden.

Sets up an expectation of step being hidden on completion.

expect_exception(expection_class)

Parameters:: expection_class – The type of the class to expect.

Sets up an expectation of an exception being raised during the runtime of the step. The expected result of the step is automatically set to EXCEPTION.

run_step(): Runs the step and validates the expectations setup before this function.

This section outlives various utilities that are useful when testing configuration written for Buildbot.

Note

At this moment the APIs outlined here are experimental and subject to change.

TestBuildStepMixin - provides a framework for testing steps
TestReactorMixin - sets up test case with mock time

Command expectations:

ExpectShell - expects shell command
ExpectStat - expects stat command
ExpectUploadFile - expects uploadFile command
ExpectDownloadFile - expects downloadFile command
ExpectMkdir - expects mkdir command
ExpectRmdir - expects rmdir command
ExpectCpdir - expects cpdir command
ExpectRmfile - expects rmfile command
ExpectGlob - expects glob command
ExpectListdir - expects listdir command

2.6. Customization

For advanced users, Buildbot acts as a framework supporting a customized build application. For the most part, such configurations consist of subclasses set up for use in a regular Buildbot configuration file.

This chapter describes some of the more common idioms in advanced Buildbot configurations.

At the moment, this chapter is an unordered set of suggestions:

If you’d like to clean it up, fork the project on GitHub and get started!

2.6.1. Programmatic Configuration Generation 

Bearing in mind that master.cfg is a Python file, large configurations can be shortened considerably by judicious use of Python loops. For example, the following will generate a builder for each of a range of supported versions of Python:

pythons = ['python2.4', 'python2.5', 'python2.6', 'python2.7',
           'python3.2', 'python3.3']
pytest_workers = ["worker%s" % n for n in range(10)]
for python in pythons:
    f = util.BuildFactory()
    f.addStep(steps.SVN(...))
    f.addStep(steps.ShellCommand(command=[python, 'test.py']))
    c['builders'].append(util.BuilderConfig(
            name="test-%s" % python,
            factory=f,
            workernames=pytest_workers))

Next step would be the loading of pythons list from a .yaml/.ini file.

2.6.2. Collapse Request Functions 

The logic Buildbot uses to decide which build request can be merged can be customized by providing a Python function (a callable) instead of True or False described in Collapsing Build Requests.

Arguments for the callable are:

master
pointer to the master object, which can be used to make additional data api calls via master.data.get

builder
dictionary of type builder

req1
dictionary of type buildrequest

req2
dictionary of type buildrequest

Warning

The number of invocations of the callable is proportional to the square of the request queue length, so a long-running callable may cause undesirable delays when the queue length grows.

It should return true if the requests can be merged, and False otherwise. For example:

@defer.inlineCallbacks
def collapseRequests(master, builder, req1, req2):
    "any requests with the same branch can be merged"

    # get the buildsets for each buildrequest
    selfBuildset , otherBuildset = yield defer.gatherResults([
        master.data.get(('buildsets', req1['buildsetid'])),
        master.data.get(('buildsets', req2['buildsetid']))
        ])
    selfSourcestamps = selfBuildset['sourcestamps']
    otherSourcestamps = otherBuildset['sourcestamps']

    if len(selfSourcestamps) != len(otherSourcestamps):
        return False

    for selfSourcestamp, otherSourcestamp in zip(selfSourcestamps, otherSourcestamps):
        if selfSourcestamp['branch'] != otherSourcestamp['branch']:
            return False

    return True

c['collapseRequests'] = collapseRequests

In many cases, the details of the sourcestamp and buildrequest are important.

In the following example, only buildrequest with the same “reason” are merged; thus developers forcing builds for different reasons will see distinct builds.

Note the use of the buildrequest.BuildRequest.canBeCollapsed method to access the source stamp compatibility algorithm:

@defer.inlineCallbacks
def collapseRequests(master, builder, req1, req2):
    canBeCollapsed = yield buildrequest.BuildRequest.canBeCollapsed(master, req1, req2)
    if canBeCollapsed and req1.reason == req2.reason:
       return True
    else:
       return False
c['collapseRequests'] = collapseRequests

Another common example is to prevent collapsing of requests coming from a Trigger step. Trigger step can indeed be used in order to implement parallel testing of the same source.

Buildrequests will all have the same sourcestamp, but probably different properties, and shall not be collapsed.

Note

In most cases, just setting collapseRequests=False for triggered builders will do the trick.

In other cases, parent_buildid from buildset can be used:

@defer.inlineCallbacks
def collapseRequests(master, builder, req1, req2):
    canBeCollapsed = yield buildrequest.BuildRequest.canBeCollapsed(master, req1, req2)
    selfBuildset , otherBuildset = yield defer.gatherResults([
        master.data.get(('buildsets', req1['buildsetid'])),
        master.data.get(('buildsets', req2['buildsetid']))
    ])
    if canBeCollapsed and selfBuildset['parent_buildid'] != None and \
            otherBuildset['parent_buildid'] != None:
        return True
    else:
        return False
c['collapseRequests'] = collapseRequests

If it’s necessary to perform some extended operation to determine whether two requests can be merged, then the collapseRequests callable may return its result via Deferred.

Warning

Again, the number of invocations of the callable is proportional to the square of the request queue length, so a long-running callable may cause undesirable delays when the queue length grows.

For example:

@defer.inlineCallbacks
def collapseRequests(master, builder, req1, req2):
    info1, info2 = yield defer.gatherResults([
        getMergeInfo(req1),
        getMergeInfo(req2),
    ])
    return info1 == info2

c['collapseRequests'] = collapseRequests

2.6.3. Builder Priority Functions 

The prioritizeBuilders configuration key specifies a function which is called with two arguments: a BuildMaster and a list of Builder objects. It should return a list of the same Builder objects, in the desired order. It may also remove items from the list if builds should not be started on those builders. If necessary, this function can return its results via a Deferred (it is called with maybeDeferred).

A simple prioritizeBuilders implementation might look like this:

def prioritizeBuilders(buildmaster, builders):
    """Prioritize builders. 'finalRelease' builds have the highest
    priority, so they should be built before running tests, or
    creating builds."""
    builderPriorities = {
        "finalRelease": 0,
        "test": 1,
        "build": 2,
    }
    builders.sort(key=lambda b: builderPriorities.get(b.name, 0))
    return builders

c['prioritizeBuilders'] = prioritizeBuilders

If the change frequency is higher than the turn-around of the builders, the following approach might be helpful:

from buildbot.util.async_sort import async_sort
from twisted.internet import defer

@defer.inlineCallbacks
def prioritizeBuilders(buildmaster, builders):
    """Prioritize builders. First, prioritize inactive builders.
    Second, consider the last time a job was completed (no job is infinite past).
    Third, consider the time the oldest request has been queued.
    This provides a simple round-robin scheme that works with collapsed builds."""

    def isBuilding(b):
        return bool(b.building) or bool(b.old_building)

    @defer.inlineCallbacks
    def key(b):
        newest_complete_time = yield b.getNewestCompleteTime()
        oldest_request_time = yield b.getOldestRequestTime()
        return (isBuilding(b), newest_complete_time, oldest_request_time)

    async_sort(builders, key)
    return builders

c['prioritizeBuilders'] = prioritizeBuilders

2.6.4. Build Priority Functions 

When a builder has multiple pending build requests, it uses a nextBuild function to decide which build it should start first. This function is given two parameters: the Builder, and a list of BuildRequest objects representing pending build requests.

A simple function to prioritize release builds over other builds might look like this:

def nextBuild(bldr, requests):
    for r in requests:
        if r.source.branch == 'release':
            return r
    return requests[0]

If some non-immediate result must be calculated, the nextBuild function can also return a Deferred:

def nextBuild(bldr, requests):
    d = get_request_priorities(requests)
    def pick(priorities):
        if requests:
            return sorted(zip(priorities, requests))[0][1]
    d.addCallback(pick)
    return d

The nextBuild function is passed as parameter to BuilderConfig:

... BuilderConfig(..., nextBuild=nextBuild, ...) ...

2.6.5. Scheduler Priority Functions 

When a Scheduler is creating a a new BuildRequest from a (list of) Change (s),it is possible to set the BuildRequest priority. This can either be an integer or a function, which receives a list of builder names and a dictionary of Change, grouped by their codebase.

A simple implementation might look like this:

def scheduler_priority(builderNames, changesByCodebase):
     priority = 0

     for codebase, changes in changesByCodebase.items():
         for chg in changes:
             if chg["branch"].startswith("dev/"):
                     priority = max(priority, 0)
             elif chg["branch"].startswith("bugfix/"):
                     priority = max(priority, 5)
             elif chg["branch"] == "main":
                     priority = max(priority, 10)

     return priority

The priority function/integer can be passed as a parameter to Scheduler:

... schedulers.SingleBranchScheduler(..., priority=scheduler_priority, ...) ...

2.6.6. `canStartBuild` Functions 

Sometimes, you cannot know in advance what workers to assign to a BuilderConfig. For example, you might need to check for the existence of a file on a worker before running a build on it. It is possible to do that by setting the canStartBuild callback.

Here is an example that checks if there is a vm property set for the build request. If it is set, it checks if a file named after it exists in the /opt/vm folder. If the file does not exist on the given worker, refuse to run the build to force the master to select another worker.

@defer.inlineCallbacks
def canStartBuild(builder, wfb, request):

    vm = request.properties.get('vm', builder.config.properties.get('vm'))
    if vm:
        args = {'file': os.path.join('/opt/vm', vm)}
        cmd = RemoteCommand('stat', args, stdioLogName=None)
        cmd.worker = wfb.worker
        res = yield cmd.run(None, wfb.worker.conn, builder.name)
        if res.rc != 0:
            return False

    return True

Here is a more complete example that checks if a worker is fit to start a build. If the load average is higher than the number of CPU cores or if there is less than 2GB of free memory, refuse to run the build on that worker. Also, put that worker in quarantine to make sure no other builds are scheduled on it for a while. Otherwise, let the build start on that worker.

class FakeBuild(object):
    properties = Properties()

class FakeStep(object):
    build = FakeBuild()

@defer.inlineCallbacks
def shell(command, worker, builder):
    args = {
        'command': command,
        'logEnviron': False,
        'workdir': worker.worker_basedir,
        'want_stdout': False,
        'want_stderr': False,
    }
    cmd = RemoteCommand('shell', args, stdioLogName=None)
    cmd.worker = worker
    yield cmd.run(FakeStep(), worker.conn, builder.name)
    return cmd.rc

@defer.inlineCallbacks
def canStartBuild(builder, wfb, request):
    # check that load is not too high
    rc = yield shell(
        'test "$(cut -d. -f1 /proc/loadavg)" -le "$(nproc)"',
        wfb.worker, builder)
    if rc != 0:
        log.msg('loadavg is too high to take new builds',
                system=repr(wfb.worker))
        wfb.worker.putInQuarantine()
        return False

    # check there is enough free memory
    sed_expr = r's/^MemAvailable:[[:space:]]+([0-9]+)[[:space:]]+kB$/\1/p'
    rc = yield shell(
        'test "$(sed -nre \'%s\' /proc/meminfo)" -gt 2000000' % sed_expr,
        wfb.worker, builder)
    if rc != 0:
        log.msg('not enough free memory to take new builds',
                system=repr(wfb.worker))
        wfb.worker.putInQuarantine()
        return False

    # The build may now proceed.
    #
    # Prevent this worker from taking any other build while this one is
    # starting for 2 min. This leaves time for the build to start consuming
    # resources (disk, memory, cpu). When the quarantine is over, if the
    # same worker is subject to start another build, the above checks will
    # better reflect the actual state of the worker.
    wfb.worker.quarantine_timeout = 120
    wfb.worker.putInQuarantine()

    # This does not take the worker out of quarantine, it only resets the
    # timeout value to default.
    wfb.worker.resetQuarantine()

    return True

You can extend these examples using any remote command described in the Master-Worker API.

2.6.7. Customizing SVNPoller 

Each source file that is tracked by a Subversion repository has a fully-qualified SVN URL in the following form: (REPOURL)(PROJECT-plus-BRANCH)(FILEPATH). When you create the SVNPoller, you give it a repourl value that includes all of the REPOURL and possibly some portion of the PROJECT-plus-BRANCH string. The SVNPoller is responsible for producing Changes that contain a branch name and a FILEPATH (which is relative to the top of a checked-out tree). The details of how these strings are split up depend upon how your repository names its branches.

2.6.7.1. `PROJECT/BRANCHNAME/FILEPATH` repositories 

One common layout is to have all the various projects that share a repository get a single top-level directory each, with branches, tags, and trunk subdirectories:

amanda/trunk
      /branches/3_2
               /3_3
      /tags/3_2_1
           /3_2_2
           /3_3_0

To set up a SVNPoller that watches the Amanda trunk (and nothing else), we would use the following, using the default split_file:

from buildbot.plugins import changes
c['change_source'] = changes.SVNPoller(
   repourl="https://svn.amanda.sourceforge.net/svnroot/amanda/amanda/trunk")

In this case, every Change that our SVNPoller produces will have its branch attribute set to None, to indicate that the Change is on the trunk. No other sub-projects or branches will be tracked.

If we want our ChangeSource to follow multiple branches, we have to do two things. First we have to change our repourl= argument to watch more than just amanda/trunk. We will set it to amanda so that we’ll see both the trunk and all the branches. Second, we have to tell SVNPoller how to split the (PROJECT-plus-BRANCH)(FILEPATH) strings it gets from the repository out into (BRANCH) and (FILEPATH).

We do the latter by providing a split_file function. This function is responsible for splitting something like branches/3_3/common-src/amanda.h into branch='branches/3_3' and filepath='common-src/amanda.h'. The function is always given a string that names a file relative to the subdirectory pointed to by the SVNPoller's repourl= argument. It is expected to return a dictionary with at least the path key. The splitter may optionally set branch, project and repository. For backwards compatibility it may return a tuple of (branchname, path). It may also return None to indicate that the file is of no interest.

Note

The function should return branches/3_3 rather than just 3_3 because the SVN checkout step, will append the branch name to the baseURL, which requires that we keep the branches component in there. Other VC schemes use a different approach towards branches and may not require this artifact.

If your repository uses this same {PROJECT}/{BRANCH}/{FILEPATH} naming scheme, the following function will work:

def split_file_branches(path):
    pieces = path.split('/')
    if len(pieces) > 1 and pieces[0] == 'trunk':
        return (None, '/'.join(pieces[1:]))
    elif len(pieces) > 2 and pieces[0] == 'branches':
        return ('/'.join(pieces[0:2]),
                '/'.join(pieces[2:]))
    else:
        return None

In fact, this is the definition of the provided split_file_branches function. So to have our Twisted-watching SVNPoller follow multiple branches, we would use this:

from buildbot.plugins import changes, util
c['change_source'] = changes.SVNPoller("svn://svn.twistedmatrix.com/svn/Twisted",
                                       split_file=util.svn.split_file_branches)

Changes for all sorts of branches (with names like "branches/1.5.x", and None to indicate the trunk) will be delivered to the Schedulers. Each Scheduler is then free to use or ignore each branch as it sees fit.

If you have multiple projects in the same repository your split function can attach a project name to the Change to help the Scheduler filter out unwanted changes:

from buildbot.plugins import util
def split_file_projects_branches(path):
    if not "/" in path:
        return None
    project, path = path.split("/", 1)
    f = util.svn.split_file_branches(path)
    if f:
        info = {"project": project, "path": f[1]}
        if f[0]:
            info['branch'] = f[0]
        return info
    return f

Again, this is provided by default. To use it you would do this:

from buildbot.plugins import changes, util
c['change_source'] = changes.SVNPoller(
   repourl="https://svn.amanda.sourceforge.net/svnroot/amanda/",
   split_file=util.svn.split_file_projects_branches)

Note here that we are monitoring at the root of the repository, and that within that repository is a amanda subdirectory which in turn has trunk and branches. It is that amanda subdirectory whose name becomes the project field of the Change.

2.6.7.2. `BRANCHNAME/PROJECT/FILEPATH` repositories 

Another common way to organize a Subversion repository is to put the branch name at the top, and the projects underneath. This is especially frequent when there are a number of related sub-projects that all get released in a group.

For example, Divmod.org hosts a project named Nevow as well as one named Quotient. In a checked-out Nevow tree there is a directory named formless that contains a Python source file named webform.py. This repository is accessible via webdav (and thus uses an http: scheme) through the divmod.org hostname. There are many branches in this repository, and they use a ({BRANCHNAME})/({PROJECT}) naming policy.

The fully-qualified SVN URL for the trunk version of webform.py is http://divmod.org/svn/Divmod/trunk/Nevow/formless/webform.py. The 1.5.x branch version of this file would have a URL of http://divmod.org/svn/Divmod/branches/1.5.x/Nevow/formless/webform.py. The whole Nevow trunk would be checked out with http://divmod.org/svn/Divmod/trunk/Nevow, while the Quotient trunk would be checked out using http://divmod.org/svn/Divmod/trunk/Quotient.

Now suppose we want to have an SVNPoller that only cares about the Nevow trunk. This case looks just like the PROJECT/BRANCH layout described earlier:

from buildbot.plugins import changes
c['change_source'] = changes.SVNPoller("http://divmod.org/svn/Divmod/trunk/Nevow")

But what happens when we want to track multiple Nevow branches? We have to point our repourl= high enough to see all those branches, but we also don’t want to include Quotient changes (since we’re only building Nevow). To accomplish this, we must rely upon the split_file function to help us tell the difference between files that belong to Nevow and those that belong to Quotient, as well as figuring out which branch each one is on.

from buildbot.plugins import changes
c['change_source'] = changes.SVNPoller("http://divmod.org/svn/Divmod",
                                       split_file=my_file_splitter)

The my_file_splitter function will be called with repository-relative pathnames like:

trunk/Nevow/formless/webform.py: This is a Nevow file, on the trunk. We want the Change that includes this to see a filename of formless/webform.py, and a branch of None
branches/1.5.x/Nevow/formless/webform.py: This is a Nevow file, on a branch. We want to get branch='branches/1.5.x' and filename='formless/webform.py'.
trunk/Quotient/setup.py: This is a Quotient file, so we want to ignore it by having my_file_splitter return None.
branches/1.5.x/Quotient/setup.py: This is also a Quotient file, which should be ignored.

The following definition for my_file_splitter will do the job:

def my_file_splitter(path):
    pieces = path.split('/')
    if pieces[0] == 'trunk':
        branch = None
        pieces.pop(0) # remove 'trunk'
    elif pieces[0] == 'branches':
        pieces.pop(0) # remove 'branches'
        # grab branch name
        branch = 'branches/' + pieces.pop(0)
    else:
        return None # something weird
    projectname = pieces.pop(0)
    if projectname != 'Nevow':
        return None # wrong project
    return {"branch": branch, "path": "/".join(pieces)}

If you later decide you want to get changes for Quotient as well you could replace the last 3 lines with simply:

return {"project": projectname, "branch": branch, "path": '/'.join(pieces)}

2.6.8. Writing Change Sources 

For some version-control systems, making Buildbot aware of new changes can be a challenge. If the pre-supplied classes in Change Sources and Changes are not sufficient, then you will need to write your own.

There are three approaches, one of which is not even a change source. The first option is to write a change source that exposes some service to which the version control system can “push” changes. This can be more complicated, since it requires implementing a new service, but delivers changes to Buildbot immediately on commit.

The second option is often preferable to the first: implement a notification service in an external process (perhaps one that is started directly by the version control system, or by an email server) and delivers changes to Buildbot via PBChangeSource. This section does not describe this particular approach, since it requires no customization within the buildmaster process.

The third option is to write a change source which polls for changes - repeatedly connecting to an external service to check for new changes. This works well in many cases, but can produce a high load on the version control system if polling is too frequent, and can take too long to notice changes if the polling is not frequent enough.

2.6.8.1. Writing a Notification-based Change Source 

A custom change source must implement buildbot.interfaces.IChangeSource.

The easiest way to do this is to subclass buildbot.changes.base.ChangeSource, implementing the describe method to describe the instance. ChangeSource is a Twisted service, so you will need to implement the startService and stopService methods to control the means by which your change source receives notifications.

When the class does receive a change, it should call self.master.data.updates.addChange(..) to submit it to the buildmaster. This method shares the same parameters as master.db.changes.addChange, so consult the API documentation for that function for details on the available arguments.

You will probably also want to set compare_attrs to the list of object attributes which Buildbot will use to compare one change source to another when reconfiguring. During reconfiguration, if the new change source is different from the old, then the old will be stopped and the new started.

2.6.8.2. Writing a Change Poller 

Polling is a very common means of seeking changes, so Buildbot supplies a utility parent class to make it easier. A poller should subclass buildbot.changes.base.ReconfigurablePollingChangeSource, which is a subclass of ChangeSource. This subclass implements the Service methods, and calls the poll method according to the pollInterval and pollAtLaunch options. The poll method should return a Deferred to signal its completion.

Aside from the service methods, the other concerns in the previous section apply here, too.

2.6.9. Writing a New Latent Worker Implementation 

Writing a new latent worker should only require subclassing buildbot.worker.AbstractLatentWorker and implementing start_instance and stop_instance at a minimum.

2.6.9.1. AbstractLatentWorker 

class buildbot.worker.AbstractLatentWorker

This class is the base class of all latent workers and implements some common functionality. A custom worker should only need to override start_instance and stop_instance methods.

See buildbot.worker.ec2.EC2LatentWorker for an example.

Additionally, builds_may_be_incompatible and isCompatibleWithBuild members must be overridden if some qualities of the new instances is determined dynamically according to the properties of an incoming build. An example a build may require a certain Docker image or amount of allocated memory. Overriding these members ensures that builds aren’t ran on incompatible workers that have already been started.

start_instance(self)

This method is responsible for starting instance that will try to connect with this master. A deferred should be returned.

Any problems should use an errback or exception. When the error is likely related to infrastructure problem and the worker should be paused in case it produces too many errors, then LatentWorkerFailedToSubstantiate should be thrown. When the error is related to the properties of the build request, such as renderable Docker image, then LatentWorkerCannotSubstantiate should be thrown.

The callback value can be None, or can be an iterable of short strings to include in the “substantiate success” status message, such as identifying the instance that started. Buildbot will ensure that a single worker will never have its start_instance called before any previous calls to start_instance or stop_instance finish. Additionally, for each start_instance call, exactly one corresponding call to stop_instance will be done eventually.

stop_instance(self, fast=False)

This method is responsible for shutting down instance. A deferred should be returned. If fast is True then the function should call back as soon as it is safe to do so, as, for example, the master may be shutting down. The value returned by the callback is ignored. Buildbot will ensure that a single worker will never have its stop_instance called before any previous calls to stop_instance finish. During master shutdown any pending calls to start_instance or stop_instance will be waited upon finish.

builds_may_be_incompatible

Determines if new instances have qualities dependent on the build. If True, the master will call isCompatibleWithBuild to determine whether new builds are compatible with the started instance. Unnecessarily setting builds_may_be_incompatible to True may result in unnecessary overhead when processing the builds. By default, this is False.

isCompatibleWithBuild(self, build_props)

This method determines whether a started instance is compatible with the build that is about to be started. build_props is the properties of the build that are known before the build has been started. A build may be incompatible with already started instance if, for example, it requests a different amount of memory or a different Docker image. A deferred should be returned, whose callback should return True if build is compatible and False otherwise. The method may be called when the instance is not yet started and should indicate compatible build in that case. In the default implementation the callback returns True.

check_instance(self)

This method determines the health of an instance. The method is expected to return a tuple with two members: is_good and message. The first member identifies whether the instance is still valid. It should be False if the method determined that a serious error has occurred and worker will not connect to the master. In such case, message should identify any additional error message that should be displayed to Buildbot user.

In case there is no additional messages, message should be an empty string.

Any exceptions raised from this method are interpreted as if the method returned False.

2.6.10. Custom Build Classes 

The standard BuildFactory object creates Build objects by default. These Builds will each execute a collection of BuildSteps in a fixed sequence. Each step can affect the results of the build, but in general there is little intelligence to tie the different steps together.

By setting the factory’s buildClass attribute to a different class, you can instantiate a different build class. This might be useful, for example, to create a build class that dynamically determines which steps to run. The skeleton of such a project would look like:

class DynamicBuild(Build):
    # override some methods
    ...

f = factory.BuildFactory()
f.buildClass = DynamicBuild
f.addStep(...)

2.6.11. Factory Workdir Functions 

Note

While the factory workdir function is still supported, it is better to just use the fact that workdir is a renderable attribute of a step. A Renderable has access to much more contextual information and can also return a deferred. So you could say build_factory.workdir = util.Interpolate("%(src:repository)s to achieve similar goal.

It is sometimes helpful to have a build’s workdir determined at runtime based on the parameters of the build. To accomplish this, set the workdir attribute of the build factory to a callable. That callable will be invoked with the list of SourceStamp for the build, and should return the appropriate workdir. Note that the value must be returned immediately - Deferreds are not supported.

This can be useful, for example, in scenarios with multiple repositories submitting changes to Buildbot. In this case you likely will want to have a dedicated workdir per repository, since otherwise a sourcing step with mode = “update” will fail as a workdir with a working copy of repository A can’t be “updated” for changes from a repository B. Here is an example how you can achieve workdir-per-repo:

def workdir(source_stamps):
    return hashlib.md5(source_stamps[0].repository).hexdigest()[:8]

build_factory = factory.BuildFactory()
build_factory.workdir = workdir

build_factory.addStep(Git(mode="update"))
# ...
builders.append ({'name': 'mybuilder',
                  'workername': 'myworker',
                  'builddir': 'mybuilder',
                  'factory': build_factory})

The end result is a set of workdirs like

Repo1 => <worker-base>/mybuilder/a78890ba
Repo2 => <worker-base>/mybuilder/0823ba88

You could make the workdir function compute other paths, based on parts of the repo URL in the sourcestamp, or lookup in a lookup table based on repo URL. As long as there is a permanent 1:1 mapping between repos and workdir, this will work.

2.6.12. Writing New BuildSteps 

Warning

The API of writing custom build steps has changed significantly in Buildbot-0.9.0. See New-Style Build Steps in Buildbot 0.9.0 for details about what has changed since pre 0.9.0 releases. This section documents new-style steps.

While it is a good idea to keep your build process self-contained in the source code tree, sometimes it is convenient to put more intelligence into your Buildbot configuration. One way to do this is to write a custom BuildStep. Once written, this Step can be used in the master.cfg file.

The best reason for writing a custom BuildStep is to better parse the results of the command being run. For example, a BuildStep that knows about JUnit could look at the logfiles to determine which tests had been run, how many passed and how many failed, and then report more detailed information than a simple rc==0 -based good/bad decision.

Buildbot has acquired a large fleet of build steps, and sports a number of knobs and hooks to make steps easier to write. This section may seem a bit overwhelming, but most custom steps will only need to apply one or two of the techniques outlined here.

For complete documentation of the build step interfaces, see BuildSteps.

2.6.12.1. Writing BuildStep Constructors 

Build steps act as their own factories, so their constructors are a bit more complex than necessary. The configuration file instantiates a BuildStep object, but the step configuration must be re-used for multiple builds, so Buildbot needs some way to create more steps.

Consider the use of a BuildStep in master.cfg:

f.addStep(MyStep(someopt="stuff", anotheropt=1))

This creates a single instance of class MyStep. However, Buildbot needs a new object each time the step is executed. An instance of BuildStep remembers how it was constructed, and can create copies of itself. When writing a new step class, then, keep in mind that you cannot do anything “interesting” in the constructor – limit yourself to checking and storing arguments.

It is customary to call the parent class’s constructor with all otherwise-unspecified keyword arguments. Keep a **kwargs argument on the end of your options, and pass that up to the parent class’s constructor.

The whole thing looks like this:

class Frobnify(BuildStep):
    def __init__(self,
            frob_what="frobee",
            frob_how_many=None,
            frob_how=None,
            **kwargs):

        # check
        if frob_how_many is None:
            raise TypeError("Frobnify argument how_many is required")

        # override a parent option
        kwargs['parentOpt'] = 'xyz'

        # call parent
        super().__init__(**kwargs)

        # set Frobnify attributes
        self.frob_what = frob_what
        self.frob_how_many = how_many
        self.frob_how = frob_how

class FastFrobnify(Frobnify):
    def __init__(self,
            speed=5,
            **kwargs):
        super().__init__(**kwargs)
        self.speed = speed

2.6.12.2. Step Execution Process 

A step’s execution occurs in its run method. When this method returns (more accurately, when the Deferred it returns fires), the step is complete. The method’s result must be an integer, giving the result of the step. Any other output from the step (logfiles, status strings, URLs, etc.) is the responsibility of the run method.

The ShellCommand class implements this run method, and in most cases steps subclassing ShellCommand simply implement some of the subsidiary methods that its run method calls.

2.6.12.3. Running Commands 

To spawn a command in the worker, create a RemoteCommand instance in your step’s run method and run it with runCommand:

cmd = RemoteCommand(args)
d = self.runCommand(cmd)

The CommandMixin class offers a simple interface to several common worker-side commands.

For the much more common task of running a shell command on the worker, use ShellMixin. This class provides a method to handle the myriad constructor arguments related to shell commands, as well as a method to create new RemoteCommand instances. This mixin is the recommended method of implementing custom shell-based steps. For simple steps that don’t involve much logic the :bb:step:`ShellCommand is recommended.

A simple example of a step using the shell mixin is:

class RunCleanup(buildstep.ShellMixin, buildstep.BuildStep):
    def __init__(self, cleanupScript='./cleanup.sh', **kwargs):
        self.cleanupScript = cleanupScript
        kwargs = self.setupShellMixin(kwargs, prohibitArgs=['command'])
        super().__init__(**kwargs)

    @defer.inlineCallbacks
    def run(self):
        cmd = yield self.makeRemoteShellCommand(
                command=[self.cleanupScript])
        yield self.runCommand(cmd)
        if cmd.didFail():
            cmd = yield self.makeRemoteShellCommand(
                    command=[self.cleanupScript, '--force'],
                    logEnviron=False)
            yield self.runCommand(cmd)
        return cmd.results()

@defer.inlineCallbacks
def run(self):
    cmd = RemoteCommand(args)
    log = yield self.addLog('output')
    cmd.useLog(log, closeWhenFinished=True)
    yield self.runCommand(cmd)

2.6.12.4. Updating Status Strings 

Each step can summarize its current status in a very short string. For example, a compile step might display the file being compiled. This information can be helpful to users eager to see their build finish.

Similarly, a build has a set of short strings collected from its steps summarizing the overall state of the build. Useful information here might include the number of tests run, but probably not the results of a make clean step.

As a step runs, Buildbot calls its getCurrentSummary method as necessary to get the step’s current status. “As necessary” is determined by calls to buildbot.process.buildstep.BuildStep.updateSummary. Your step should call this method every time the status summary may have changed. Buildbot will take care of rate-limiting summary updates.

When the step is complete, Buildbot calls its getResultSummary method to get a final summary of the step along with a summary for the build.

2.6.12.5. About Logfiles 

Each BuildStep has a collection of log files. Each one has a short name, like stdio or warnings. Each log file contains an arbitrary amount of text, usually the contents of some output file generated during a build or test step, or a record of everything that was printed to stdout/stderr during the execution of some command.

Each can contain multiple channels, generally limited to three basic ones: stdout, stderr, and headers. For example, when a shell command runs, it writes a few lines to the headers channel to indicate the exact argv strings being run, which directory the command is being executed in, and the contents of the current environment variables. Then, as the command runs, it adds a lot of stdout and stderr messages. When the command finishes, a final header line is added with the exit code of the process.

Status display plugins can format these different channels in different ways. For example, the web page shows log files as text/html, with header lines in blue text, stdout in black, and stderr in red. A different URL is available which provides a text/plain format, in which stdout and stderr are collapsed together, and header lines are stripped completely. This latter option makes it easy to save the results to a file and run grep or whatever against the output.

2.6.12.6. Writing Log Files 

Most commonly, logfiles come from commands run on the worker. Internally, these are configured by supplying the RemoteCommand instance with log files via the useLog method:

@defer.inlineCallbacks
def run(self):
    ...
    log = yield self.addLog('stdio')
    cmd.useLog(log, closeWhenFinished=True, 'stdio')
    yield self.runCommand(cmd)

The name passed to useLog must match that configured in the command. In this case, stdio is the default.

If the log file was already added by another part of the step, it can be retrieved with getLog:

stdioLog = self.getLog('stdio')

Less frequently, some master-side processing produces a log file. If this log file is short and easily stored in memory, this is as simple as a call to addCompleteLog:

@defer.inlineCallbacks
def run(self):
    ...
    summary = u'\n'.join('%s: %s' % (k, count)
                         for (k, count) in self.lint_results.items())
    yield self.addCompleteLog('summary', summary)

Note that the log contents must be a unicode string.

Longer logfiles can be constructed line-by-line using the add methods of the log file:

@defer.inlineCallbacks
def run(self):
    ...
    updates = yield self.addLog('updates')
    while True:
        ...
        yield updates.addStdout(some_update)

Again, note that the log input must be a unicode string.

Finally, addHTMLLog is similar to addCompleteLog, but the resulting log will be tagged as containing HTML. The web UI will display the contents of the log using the browser.

The logfiles= argument to ShellCommand and its subclasses creates new log files and fills them in realtime by asking the worker to watch an actual file on disk. The worker will look for additions in the target file and report them back to the BuildStep. These additions will be added to the log file by calling addStdout.

All log files can be used as the source of a LogObserver just like the normal stdio LogFile. In fact, it’s possible for one LogObserver to observe a logfile created by another.

2.6.12.7. Reading Logfiles 

For the most part, Buildbot tries to avoid loading the contents of a log file into memory as a single string. For large log files on a busy master, this behavior can quickly consume a great deal of memory.

Instead, steps should implement a LogObserver to examine log files one chunk or line at a time.

For commands which only produce a small quantity of output, RemoteCommand will collect the command’s stdout into its stdout attribute if given the collectStdout=True constructor argument.

2.6.12.8. Adding LogObservers 

Most shell commands emit messages to stdout or stderr as they operate, especially if you ask them nicely with a option –verbose flag of some sort. They may also write text to a log file while they run. Your BuildStep can watch this output as it arrives, to keep track of how much progress the command has made or to process log output for later summarization.

To accomplish this, you will need to attach a LogObserver to the log. This observer is given all text as it is emitted from the command, and has the opportunity to parse that output incrementally.

There are a number of pre-built LogObserver classes that you can choose from (defined in buildbot.process.buildstep, and of course you can subclass them to add further customization. The LogLineObserver class handles the grunt work of buffering and scanning for end-of-line delimiters, allowing your parser to operate on complete stdout/stderr lines.

For example, let’s take a look at the TrialTestCaseCounter, which is used by the Trial step to count test cases as they are run. As Trial executes, it emits lines like the following:

buildbot.test.test_config.ConfigTest.testDebugPassword ... [OK]
buildbot.test.test_config.ConfigTest.testEmpty ... [OK]
buildbot.test.test_config.ConfigTest.testIRC ... [FAIL]
buildbot.test.test_config.ConfigTest.testLocks ... [OK]

When the tests are finished, trial emits a long line of ====== and then some lines which summarize the tests that failed. We want to avoid parsing these trailing lines, because their format is less well-defined than the [OK] lines.

A simple version of the parser for this output looks like this. The full version is in master/buildbot/steps/python_twisted.py.

from buildbot.plugins import util

class TrialTestCaseCounter(util.LogLineObserver):
    _line_re = re.compile(r'^([\w\.]+) \.\.\. \[([^\]]+)\]$')
    numTests = 0
    finished = False

    def outLineReceived(self, line):
        if self.finished:
            return
        if line.startswith("=" * 40):
            self.finished = True
            return

        m = self._line_re.search(line.strip())
        if m:
            testname, result = m.groups()
            self.numTests += 1
            self.step.setProgress('tests', self.numTests)

This parser only pays attention to stdout, since that’s where trial writes the progress lines. It has a mode flag named finished to ignore everything after the ==== marker, and a scary-looking regular expression to match each line while hopefully ignoring other messages that might get displayed as the test runs.

Each time it identifies that a test has been completed, it increments its counter and delivers the new progress value to the step with self.step.setProgress. This helps Buildbot to determine the ETA for the step.

To connect this parser into the Trial build step, Trial.__init__ ends with the following clause:

# this counter will feed Progress along the 'test cases' metric
counter = TrialTestCaseCounter()
self.addLogObserver('stdio', counter)
self.progressMetrics += ('tests',)

This creates a TrialTestCaseCounter and tells the step that the counter wants to watch the stdio log. The observer is automatically given a reference to the step in its step attribute.

2.6.12.9. Using Properties 

In custom BuildSteps, you can get and set the build properties with the getProperty and setProperty methods. Each takes a string for the name of the property, and returns or accepts an arbitrary JSON-able (lists, dicts, strings, and numbers) object. For example:

class MakeTarball(buildstep.ShellMixin, buildstep.BuildStep):
    def __init__(self, **kwargs):
        kwargs = self.setupShellMixin(kwargs)
        super().__init__(**kwargs)

    @defer.inlineCallbacks
    def run(self):
        if self.getProperty("os") == "win":
            # windows-only command
            cmd = yield self.makeRemoteShellCommand(commad=[ ... ])
        else:
            # equivalent for other systems
            cmd = yield self.makeRemoteShellCommand(commad=[ ... ])
        yield self.runCommand(cmd)
        return cmd.results()

Remember that properties set in a step may not be available until the next step begins. In particular, any Property or Interpolate instances for the current step are interpolated before the step starts, so they cannot use the value of any properties determined in that step.

2.6.12.10. Using Statistics 

Statistics can be generated for each step, and then summarized across all steps in a build. For example, a test step might set its warnings statistic to the number of warnings observed. The build could then sum the warnings on all steps to get a total number of warnings.

Statistics are set and retrieved with the setStatistic and getStatistic methods. The hasStatistic method determines whether a statistic exists.

The Build method getSummaryStatistic can be used to aggregate over all steps in a Build.

2.6.12.11. BuildStep URLs 

Each BuildStep has a collection of links. Each has a name and a target URL. The web display displays clickable links for each link, making them a useful way to point to extra information about a step. For example, a step that uploads a build result to an external service might include a link to the uploaded file.

To set one of these links, the BuildStep should call the addURL method with the name of the link and the target URL. Multiple URLs can be set. For example:

@defer.inlineCallbacks
def run(self):
    ... # create and upload report to coverage server
    url = 'http://coverage.example.com/reports/%s' % reportname
    yield self.addURL('coverage', url)

This also works from log observers, which is helpful for instance if the build output points to an external page such as a detailed log file. The following example parses output of poudriere, a tool for building packages on the FreeBSD operating system.

Example output:

[00:00:00] Creating the reference jail... done
...
[00:00:01] Logs: /usr/local/poudriere/data/logs/bulk/103amd64-2018Q4/2018-10-03_05h47m30s
...
... build log without details (those are in the above logs directory) ...

Log observer implementation:

c = BuildmasterConfig = {}
c['titleURL'] = 'https://my-buildbot.example.com/'
# ...
class PoudriereLogLinkObserver(util.LogLineObserver):
    _regex = re.compile(
        r'Logs: /usr/local/poudriere/data/logs/bulk/([-_/0-9A-Za-z]+)$')

    def __init__(self):
        super().__init__()
        self._finished = False

    def outLineReceived(self, line):
        # Short-circuit if URL already found
        if self._finished:
            return

        m = self._regex.search(line.rstrip())
        if m:
            self._finished = True
            # Let's assume local directory /usr/local/poudriere/data/logs/bulk
            # is available as https://my-buildbot.example.com/poudriere/logs
            poudriere_ui_url = c['titleURL'] + 'poudriere/logs/' + m.group(1)
            # Add URLs for build overview page and for per-package log files
            self.step.addURL('Poudriere build web interface', poudriere_ui_url)
            self.step.addURL('Poudriere logs', poudriere_ui_url + '/logs/')

2.6.12.12. Discovering files 

When implementing a BuildStep it may be necessary to know about files that are created during the build. There are a few worker commands that can be used to find files on the worker and test for the existence (and type) of files and directories.

The worker provides the following file-discovery related commands:

stat calls os.stat for a file in the worker’s build directory. This can be used to check if a known file exists and whether it is a regular file, directory or symbolic link.
listdir calls os.listdir for a directory on the worker. It can be used to obtain a list of files that are present in a directory on the worker.
glob calls glob.glob on the worker, with a given shell-style pattern containing wildcards.

For example, we could use stat to check if a given path exists and contains *.pyc files. If the path does not exist (or anything fails) we mark the step as failed; if the path exists but is not a directory, we mark the step as having “warnings”.

from buildbot.plugins import steps, util
from buildbot.process import remotecommand
from buildbot.interfaces import WorkerSetupError
import stat

class MyBuildStep(steps.BuildStep):

    def __init__(self, dirname, **kwargs):
        super().__init__(**kwargs)
        self.dirname = dirname

    @defer.inlineCallbacks
    def run(self):
        # make sure the worker knows about stat
        workerver = (self.workerVersion('stat'),
                    self.workerVersion('glob'))
        if not all(workerver):
            raise WorkerSetupError('need stat and glob')

        cmd = remotecommand.RemoteCommand('stat', {'file': self.dirname})

        yield self.runCommand(cmd)

        if cmd.didFail():
            self.description = ["File not found."]
            return util.FAILURE

        s = cmd.updates["stat"][-1]
        if not stat.S_ISDIR(s[stat.ST_MODE]):
            self.description = ["'tis not a directory"]
            return util.WARNINGS

        cmd = remotecommand.RemoteCommand('glob', {'path': self.dirname + '/*.pyc'})

        yield self.runCommand(cmd)

        if cmd.didFail():
            self.description = ["Glob failed."]
            return util.FAILURE

        files = cmd.updates["files"][-1]
        if len(files):
            self.description = ["Found pycs"] + files
        else:
            self.description = ["No pycs found"]
        return util.SUCCESS

For more information on the available commands, see Master-Worker API.

Todo

Step Progress BuildStepFailed

2.6.13. Writing Dashboards with Flask or Bottle 

Buildbot Nine UI is written in Javascript. This allows it to be reactive and real time, but comes at a price of a fair complexity.

There is a Buildbot plugin which allows to write a server side generated dashboard, and integrate it in the UI.

# This needs buildbot and buildbot_www >= 0.9.5
pip install buildbot_wsgi_dashboards flask

This plugin can use any WSGI compatible web framework, Flask is a very common one, Bottle is another popular option.
The application needs to implement a /index.html route, which will render the html code representing the dashboard.
The application framework runs in a thread outside of Twisted. No need to worry about Twisted and asynchronous code. You can use python-requests or any library from the python ecosystem to access other servers.
You could use HTTP in order to access Buildbot REST API, but you can also use the Data API, via the provided synchronous wrapper.
buildbot_api.dataGet(path, filters=None, fields=None, order=None, limit=None, offset=None)
Parameters:

path (tuple) – A tuple of path elements representing the API path to fetch. Numbers can be passed as strings or integers.

filters – result spec filters

fields – result spec fields

order – result spec order

limit – result spec limit

offset – result spec offset

Raises:

InvalidPathError

Returns:

a resource or list, or None

This is a blocking wrapper to master.data.get as described in Data API. The available paths are described in the REST API, as well as the nature of return values depending on the kind of data that is fetched. Path can be either the REST path e.g. "builders/2/builds/4" or tuple e.g. ("builders", 2, "builds", 4). The latter form being more convenient if some path parts are coming from variables. The Data API and REST API are functionally equivalent except:

Data API does not have HTTP connection overhead.

Data API does not enforce authorization rules.

buildbot_api.dataGet is accessible via the WSGI application object passed to wsgi_dashboards plugin (as per the example).
That html code output of the server runs inside AngularJS application.
- It will use the CSS of the AngularJS application (including the Bootstrap CSS base). You can use custom style-sheet with a standard style tag within your html. Custom CSS will be shared with the whole Buildbot application once your dashboard is loaded. So you should make sure your custom CSS rules only apply to your dashboard (e.g. by having a specific class for your dashboard’s main div)
- It can use some of the AngularJS directives defined by Buildbot UI (currently only buildsummary is usable).
- It has full access to the application JS context.

2.6.14. A Somewhat Whimsical Example (or “It’s now customized, how do I deploy it?”)

Let’s say that we’ve got some snazzy new unit-test framework called Framboozle. It’s the hottest thing since sliced bread. It slices, it dices, it runs unit tests like there’s no tomorrow. Plus if your unit tests fail, you can use its name for a Web 2.1 startup company, make millions of dollars, and hire engineers to fix the bugs for you, while you spend your afternoons lazily hang-gliding along a scenic pacific beach, blissfully unconcerned about the state of your tests. [1]

To run a Framboozle-enabled test suite, you just run the ‘framboozler’ command from the top of your source code tree. The ‘framboozler’ command emits a bunch of stuff to stdout, but the most interesting bit is that it emits the line “FNURRRGH!” every time it finishes running a test case You’d like to have a test-case counting LogObserver that watches for these lines and counts them, because counting them will help the buildbot more accurately calculate how long the build will take, and this will let you know exactly how long you can sneak out of the office for your hang-gliding lessons without anyone noticing that you’re gone.

This will involve writing a new BuildStep (probably named “Framboozle”) which inherits from ShellCommand. The BuildStep class definition itself will look something like this:

from buildbot.plugins import steps, util

class FNURRRGHCounter(util.LogLineObserver):
    numTests = 0
    def outLineReceived(self, line):
        if "FNURRRGH!" in line:
            self.numTests += 1
            self.step.setProgress('tests', self.numTests)

class Framboozle(steps.ShellCommand):
    command = ["framboozler"]

    def __init__(self, **kwargs):
        super().__init__(**kwargs)   # always upcall!
        counter = FNURRRGHCounter()
        self.addLogObserver('stdio', counter)
        self.progressMetrics += ('tests',)

So that’s the code that we want to wind up using. How do we actually deploy it?

You have a number of different options:

2.6.14.1. Inclusion in the `master.cfg` file 

The simplest technique is to simply put the step class definitions in your master.cfg file, somewhere before the BuildFactory definition where you actually use it in a clause like:

f = BuildFactory()
f.addStep(SVN(repourl="stuff"))
f.addStep(Framboozle())

Remember that master.cfg is secretly just a Python program with one job: populating the BuildmasterConfig dictionary. And Python programs are allowed to define as many classes as they like. So you can define classes and use them in the same file, just as long as the class is defined before some other code tries to use it.

This is easy, and it keeps the point of definition very close to the point of use, and whoever replaces you after that unfortunate hang-gliding accident will appreciate being able to easily figure out what the heck this stupid “Framboozle” step is doing anyways. The downside is that every time you reload the config file, the Framboozle class will get redefined, which means that the buildmaster will think that you’ve reconfigured all the Builders that use it, even though nothing changed. Bleh.

2.6.14.2. Python file somewhere on the system 

Instead, we can put this code in a separate file, and import it into the master.cfg file just like we would the normal buildsteps like ShellCommand and SVN.

Create a directory named ~/lib/python, put the step class definitions in ~/lib/python/framboozle.py, and run your buildmaster using:

PYTHONPATH=~/lib/python buildbot start MASTERDIR

or use the Makefile.buildbot to control the way buildbot start works. Or add something like this to something like your ~/.bashrc or ~/.bash_profile or ~/.cshrc:

export PYTHONPATH=~/lib/python

Once we’ve done this, our master.cfg can look like:

from framboozle import Framboozle
f = BuildFactory()
f.addStep(SVN(repourl="stuff"))
f.addStep(Framboozle())

or:

import framboozle
f = BuildFactory()
f.addStep(SVN(repourl="stuff"))
f.addStep(framboozle.Framboozle())

(check out the Python docs for details about how import and from A import B work).

What we’ve done here is to tell Python that every time it handles an “import” statement for some named module, it should look in our ~/lib/python/ for that module before it looks anywhere else. After our directories, it will try in a bunch of standard directories too (including the one where buildbot is installed). By setting the PYTHONPATH environment variable, you can add directories to the front of this search list.

Python knows that once it “import”s a file, it doesn’t need to re-import it again. This means that reconfiguring the buildmaster (with buildbot reconfig, for example) won’t make it think the Framboozle class has changed every time, so the Builders that use it will not be spuriously restarted. On the other hand, you either have to start your buildmaster in a slightly weird way, or you have to modify your environment to set the PYTHONPATH variable.

2.6.14.3. Install this code into a standard Python library directory 

Find out what your Python’s standard include path is by asking it:

80:warner@luther% python
Python 2.4.4c0 (#2, Oct  2 2006, 00:57:46)
[GCC 4.1.2 20060928 (prerelease) (Debian 4.1.1-15)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> import pprint
>>> pprint.pprint(sys.path)
['',
 '/usr/lib/python24.zip',
 '/usr/lib/python2.4',
 '/usr/lib/python2.4/plat-linux2',
 '/usr/lib/python2.4/lib-tk',
 '/usr/lib/python2.4/lib-dynload',
 '/usr/local/lib/python2.4/site-packages',
 '/usr/lib/python2.4/site-packages',
 '/usr/lib/python2.4/site-packages/Numeric',
 '/var/lib/python-support/python2.4',
 '/usr/lib/site-python']

In this case, putting the code into /usr/local/lib/python2.4/site-packages/framboozle.py would work just fine. We can use the same master.cfg import framboozle statement as in Option 2. By putting it in a standard include directory (instead of the decidedly non-standard ~/lib/python), we don’t even have to set PYTHONPATH to anything special. The downside is that you probably have to be root to write to one of those standard include directories.

2.6.14.4. Distribute a Buildbot Plug-In 

First of all, you must prepare a Python package (if you do not know what that is, please check How to package Buildbot plugins, where you can find a couple of pointers to tutorials).

When you have a package, you will have a special file called setup.py. This file needs to be updated to include a pointer to your new step:

setup(
    ...
    entry_points = {
        ...,
        'buildbot.steps': [
            'Framboozle = framboozle:Framboozle'
        ]
    },
    ...
)

Where:

buildbot.steps is the kind of plugin you offer (more information about possible kinds you can find in How to package Buildbot plugins)
framboozle:Framboozle consists of two parts: framboozle is the name of the Python module where to look for Framboozle class, which implements the plugin
Framboozle is the name of the plugin.

This will allow users of your plugin to use it just like any other Buildbot plugins:
```
from buildbot.plugins import steps

... steps.Framboozle ...
```

Now you can upload it to PyPI where other people can download it from and use in their build systems. Once again, the information about how to prepare and upload a package to PyPI can be found in tutorials listed in How to package Buildbot plugins.

2.6.14.5. Submit the code for inclusion in the Buildbot distribution 

Make a fork of buildbot on http://github.com/buildbot/buildbot or post a patch in a bug at http://trac.buildbot.net/. In either case, post a note about your patch to the mailing list, so others can provide feedback and, eventually, commit it.

When it’s committed to the master, the usage is the same as in the previous approach:

from buildbot.plugins import steps, util

...
f = util.BuildFactory()
f.addStep(steps.SVN(repourl="stuff"))
f.addStep(steps.Framboozle())
...

And then you don’t even have to install framboozle.py anywhere on your system, since it will ship with Buildbot. You don’t have to be root, you don’t have to set PYTHONPATH. But you do have to make a good case for Framboozle being worth going into the main distribution, you’ll probably have to provide docs and some unit test cases, you’ll need to figure out what kind of beer the author likes (IPA’s and Stouts for Dustin), and then you’ll have to wait until the next release. But in some environments, all this is easier than getting root on your buildmaster box, so the tradeoffs may actually be worth it.

2.6.14.6. Summary 

Putting the code in master.cfg (1) makes it available to that buildmaster instance. Putting it in a file in a personal library directory (2) makes it available for any buildmasters you might be running. Putting it in a file in a system-wide shared library directory (3) makes it available for any buildmasters that anyone on that system might be running. Getting it into the buildbot’s upstream repository (4) makes it available for any buildmasters that anyone in the world might be running. It’s all a matter of how widely you want to deploy that new class.

2.7. Command-line Tool

This section describes command-line tools available after buildbot installation.

The two main command-line tools are buildbot and buildbot-worker. The former handles a Buildbot master and the former handles a Buildbot worker.

Every command-line tool has a list of global options and a set of commands which have their own options. One can run these tools in the following way:

buildbot [global options] command [command options]
buildbot-worker [global options] command [command options]

The buildbot command is used on the master, while buildbot-worker is used on the worker. Global options are the same for both tools which perform the following actions:

--help: Print general help about available commands and global options and exit. All subsequent arguments are ignored.
--verbose: Set verbose output.
--version: Print current buildbot version and exit. All subsequent arguments are ignored.

You can get help on any command by specifying --help as a command option:

buildbot command --help

You can also use manual pages for buildbot and buildbot-worker for quick reference on command-line options.

The remainder of this section describes each buildbot command. See Command Line Index for a full list.

2.7.1. buildbot

The buildbot command-line tool can be used to start or stop a buildmaster or buildbot, and to interact with a running buildmaster. Some of its subcommands are intended for buildmaster admins, while some are for developers who are editing the code that the buildbot is monitoring.

2.7.1.1. Administrator Tools

The following buildbot sub-commands are intended for buildmaster administrators:

create-master

buildbot create-master -r {BASEDIR}

This creates a new directory and populates it with files that allow it to be used as a buildmaster’s base directory.

You will usually want to use the option -r option to create a relocatable buildbot.tac. This allows you to move the master directory without editing this file.

upgrade-master

buildbot upgrade-master {BASEDIR}

This upgrades a previously created buildmaster’s base directory for a new version of buildbot master source code. This will copy the web server static files, and potentially upgrade the db.

start

buildbot start [--nodaemon] {BASEDIR}

This starts a buildmaster which was already created in the given base directory. The daemon is launched in the background, with events logged to a file named twistd.log.

The option –nodaemon option instructs Buildbot to skip daemonizing. The process will start in the foreground. It will only return to the command-line when it is stopped.

restart

buildbot restart [--nodaemon] {BASEDIR}

Restart the buildmaster. This is equivalent to stop followed by start The option –nodaemon option has the same meaning as for start.

stop

buildbot stop {BASEDIR}

This terminates the daemon (either buildmaster or worker) running in the given directory. The --clean option shuts down the buildmaster cleanly. With --no-wait option buildbot stop command will send buildmaster shutdown signal and will immediately exit, not waiting for complete buildmaster shutdown.

sighup

buildbot sighup {BASEDIR}

This sends a SIGHUP to the buildmaster running in the given directory, which causes it to re-read its master.cfg file.

checkconfig

buildbot checkconfig {BASEDIR|CONFIG_FILE}

This checks if the buildmaster configuration is well-formed and contains no deprecated or invalid elements. If no arguments are used or the base directory is passed as the argument the config file specified in buildbot.tac is checked. If the argument is the path to a config file then it will be checked without using the buildbot.tac file.

cleanupdb

buildbot cleanupdb {BASEDIR|CONFIG_FILE} [-q]

This command is frontend for various database maintenance jobs:

optimiselogs: This optimization groups logs into bigger chunks to apply higher level of compression.

copy-db

buildbot copy-db {DESTINATION_URL} {BASEDIR} [-q]

This command copies all buildbot data from source database configured in the buildbot configuration file to the destination database. The URL of the destination database is specified on the command line. The destination database may have different type from the source database.

The destination database must be empty. The script will initialize it in the same way as if a new Buildbot installation was created.

Source database must be already upgraded to the current Buildbot version by the buildbot upgrade-master command.

2.7.1.2. Developer Tools

These tools are provided for use by the developers who are working on the code that the buildbot is monitoring.

try

This lets a developer to ask the question What would happen if I committed this patch right now?. It runs the unit test suite (across multiple build platforms) on the developer’s current code, allowing them to make sure they will not break the tree when they finally commit their changes.

The buildbot try command is meant to be run from within a developer’s local tree, and starts by figuring out the base revision of that tree (what revision was current the last time the tree was updated), and a patch that can be applied to that revision of the tree to make it match the developer’s copy. This (revision, patch) pair is then sent to the buildmaster, which runs a build with that SourceStamp. If you want, the tool will emit status messages as the builds run, and will not terminate until the first failure has been detected (or the last success).

There is an alternate form which accepts a pre-made patch file (typically the output of a command like svn diff). This --diff form does not require a local tree to run from. See try –diff concerning the --diff command option.

For this command to work, several pieces must be in place: the Try_Jobdir or :Try_Userpass, as well as some client-side configuration.

Locating the master

The try command needs to be told how to connect to the try scheduler, and must know which of the authentication approaches described above is in use by the buildmaster. You specify the approach by using --connect=ssh or --connect=pb (or try_connect = 'ssh' or try_connect = 'pb' in .buildbot/options).

For the PB approach, the command must be given a option –master argument (in the form HOST:PORT) that points to TCP port that you picked in the Try_Userpass scheduler. It also takes a option –username and option –passwd pair of arguments that match one of the entries in the buildmaster’s userpass list. These arguments can also be provided as try_master, try_username, and try_password entries in the .buildbot/options file.

For the SSH approach, the command must be given option –host and option –username, to get to the buildmaster host. It must also be given option –jobdir, which points to the inlet directory configured above. The jobdir can be relative to the user’s home directory, but most of the time you will use an explicit path like ~buildbot/project/trydir. These arguments can be provided in .buildbot/options as try_host, try_username, try_password, and try_jobdir.

If you need to use something different from the default ssh command for connecting to the remote system, you can use –ssh command line option or try_ssh in the configuration file.

The SSH approach also provides a option –buildbotbin argument to allow specification of the buildbot binary to run on the buildmaster. This is useful in the case where buildbot is installed in a virtualenv on the buildmaster host, or in other circumstances where the buildbot command is not on the path of the user given by option –username. The option –buildbotbin argument can be provided in .buildbot/options as try_buildbotbin

The following command line arguments are deprecated, but retained for backward compatibility:

--tryhost: is replaced by option –host
--trydir: is replaced by option –jobdir
--master: is replaced by option –masterstatus

Likewise, the following .buildbot/options file entries are deprecated, but retained for backward compatibility:

try_dir is replaced by try_jobdir

masterstatus is replaced by try_masterstatus

Waiting for results

If you provide the option –wait option (or try_wait = True in .buildbot/options), the buildbot try command will wait until your changes have either been proven good or bad before exiting. Unless you use the option –quiet option (or try_quiet=True), it will emit a progress message every 60 seconds until the builds have completed.

The SSH connection method does not support waiting for results.

Choosing the Builders

A trial build is performed on multiple Builders at the same time, and the developer gets to choose which Builders are used (limited to a set selected by the buildmaster admin with the TryScheduler’s builderNames= argument). The set you choose will depend upon what your goals are: if you are concerned about cross-platform compatibility, you should use multiple Builders, one from each platform of interest. You might use just one builder if that platform has libraries or other facilities that allow better test coverage than what you can accomplish on your own machine, or faster test runs.

The set of Builders to use can be specified with multiple option –builder arguments on the command line. It can also be specified with a single try_builders option in .buildbot/options that uses a list of strings to specify all the Builder names:

try_builders = ["full-OSX", "full-win32", "full-linux"]

If you are using the PB approach, you can get the names of the builders that are configured for the try scheduler using the get-builder-names argument:

buildbot try --get-builder-names --connect=pb --master=... --username=... --passwd=...

Specifying the VC system

The try command also needs to know how to take the developer’s current tree and extract the (revision, patch) source-stamp pair. Each VC system uses a different process, so you start by telling the try command which VC system you are using, with an argument like option –vc=cvs or option –vc=git. This can also be provided as try_vc in .buildbot/options.

The following names are recognized: bzr cvs darcs hg git mtn p4 svn

Finding the top of the tree

Some VC systems (notably CVS and SVN) track each directory more-or-less independently, which means the try command needs to move up to the top of the project tree before it will be able to construct a proper full-tree patch. To accomplish this, the try command will crawl up through the parent directories until it finds a marker file. The default name for this marker file is .buildbot-top, so when you are using CVS or SVN you should touch .buildbot-top from the top of your tree before running buildbot try. Alternatively, you can use a filename like ChangeLog or README, since many projects put one of these files in their top-most directory (and nowhere else). To set this filename, use --topfile=ChangeLog, or set it in the options file with try_topfile = 'ChangeLog'.

You can also manually set the top of the tree with --topdir=~/trees/mytree, or try_topdir = '~/trees/mytree'. If you use try_topdir, in a .buildbot/options file, you will need a separate options file for each tree you use, so it may be more convenient to use the try_topfile approach instead.

Other VC systems which work on full projects instead of individual directories (Darcs, Mercurial, Git, Monotone) do not require try to know the top directory, so the option –try-topfile and option –try-topdir arguments will be ignored.

If the try command cannot find the top directory, it will abort with an error message.

The following command line arguments are deprecated, but retained for backward compatibility:

--try-topdir is replaced by option –topdir
--try-topfile is replaced by option –topfile

Determining the branch name

Some VC systems record the branch information in a way that try can locate it. For the others, if you are using something other than the default branch, you will have to tell the buildbot which branch your tree is using. You can do this with either the option –branch argument, or a try_branch entry in the .buildbot/options file.

Determining the revision and patch

Each VC system has a separate approach for determining the tree’s base revision and computing a patch.

CVS: try pretends that the tree is up to date. It converts the current time into a option -D time specification, uses it as the base revision, and computes the diff between the upstream tree as of that point in time versus the current contents. This works, more or less, but requires that the local clock be in reasonably good sync with the repository.
SVN: try does a svn status -u to find the latest repository revision number (emitted on the last line in the Status against revision: NN message). It then performs an svn diff -rNN to find out how your tree differs from the repository version, and sends the resulting patch to the buildmaster. If your tree is not up to date, this will result in the try tree being created with the latest revision, then backwards patches applied to bring it back to the version you actually checked out (plus your actual code changes), but this will still result in the correct tree being used for the build.
bzr: try does a bzr revision-info to find the base revision, then a bzr diff -r$base.. to obtain the patch.
Mercurial: hg parents --template '{node}\n' emits the full revision id (as opposed to the common 12-char truncated) which is a SHA1 hash of the current revision’s contents. This is used as the base revision. hg diff then provides the patch relative to that revision. For try to work, your working directory must only have patches that are available from the same remotely-available repository that the build process’ source.Mercurial will use.
Perforce: try does a p4 changes -m1 ... to determine the latest changelist and implicitly assumes that the local tree is synced to this revision. This is followed by a p4 diff -du to obtain the patch. A p4 patch differs slightly from a normal diff. It contains full depot paths and must be converted to paths relative to the branch top. To convert the following restriction is imposed. The p4base (see P4Source) is assumed to be //depot
Darcs: try does a darcs changes --context to find the list of all patches back to and including the last tag that was made. This text file (plus the location of a repository that contains all these patches) is sufficient to re-create the tree. Therefore the contents of this context file are the revision stamp for a Darcs-controlled source tree. It then does a darcs diff -u to compute the patch relative to that revision.
Git: git branch -v lists all the branches available in the local repository along with the revision ID it points to and a short summary of the last commit. The line containing the currently checked out branch begins with “* ” (star and space) while all the others start with ” ” (two spaces). try scans for this line and extracts the branch name and revision from it. Then it generates a diff against the base revision.

Todo

I’m not sure if this actually works the way it’s intended since the extracted base revision might not actually exist in the upstream repository. Perhaps we need to add a –remote option to specify the remote tracking branch to generate a diff against.

Monotone: mtn automate get_base_revision_id emits the full revision id which is a SHA1 hash of the current revision’s contents. This is used as the base revision. mtn diff then provides the patch relative to that revision. For try to work, your working directory must only have patches that are available from the same remotely-available repository that the build process’ source.Monotone will use.

patch information

You can provide the option –who=dev to designate who is running the try build. This will add the dev to the Reason field on the try build’s status web page. You can also set try_who = dev in the .buildbot/options file. Note that option –who=dev will not work on version 0.8.3 or earlier masters.

Similarly, option –comment=COMMENT will specify the comment for the patch, which is also displayed in the patch information. The corresponding config-file option is try_comment.

Sending properties

You can set properties to send with your change using either the option –property=key=value option, which sets a single property, or the option –properties=key1=value1,key2=value2… option, which sets multiple comma-separated properties. Either of these can be specified multiple times. Note that the option –properties option uses commas to split on properties, so if your property value itself contains a comma, you’ll need to use the option –property option to set it.

try –diff

Sometimes you might have a patch from someone else that you want to submit to the buildbot.