Buildbot: a Python CI framework you run yourself, from master to worker

What Buildbot solves and who ends up running it

Buildbot is a continuous integration framework written in Python. The README describes it plainly as "The Continuous Integration Framework" and lists the pieces it consists of: a master, a worker, and web front ends under www/. That split is the whole design. The master holds the configuration and the build history; workers are the machines that actually execute build steps; the web packages serve the dashboards people look at.

This is a framework, not a service. There is no hosted Buildbot that signs in to your repository and starts running jobs. You install the master somewhere, you install a worker on each machine that should run builds, and you write the configuration that connects them. The project is maintained by a group the README calls "the Botherders" and points to buildbot.net and a Discord server for contact.

Who is it for? Teams with machines they control: a rack of build boxes, a lab of embedded boards, or a set of platforms that a hosted CI provider does not offer as runner images. The repository layout reinforces this. There are dedicated requirements files for the master, the worker and the CI database, and a Dockerfile.master at the top level, which tells you the maintainers expect the master to be deployed as a long-running service rather than invoked per commit.

Master, worker and www: how the pieces fit together

The top-level repository entries map directly onto the architecture. master/ holds the Buildbot master package, worker/ holds the worker package, and www/ contains the web packages: base, console_view, grid_view, waterfall_view, wsgi_dashboards and badges, with shared packages such as plugin_support, data-module and ui underneath. The Makefile lists these explicitly in WWW_PKGS and WWW_DEP_PKGS, and excludes badges and wsgi_dashboards from the unit test set, which is a useful hint about which front ends the maintainers exercise most heavily.

Data flows one way in the obvious sense: the master decides what to build, a worker connects to the master and receives build steps, executes them, and reports results back. The master persists build and step results, and the web packages read from that data layer through the data-module package rather than talking to workers directly.

The configuration itself is Python. That is the dividing line between Buildbot and most of what people compare it to. A CI pipeline here is code that constructs objects, not a declarative document parsed by someone else's engine. It buys you loops, conditionals, imported helper modules and generated step lists. It costs you the ability to hand the pipeline to a reviewer who does not read Python, and it means a configuration mistake can be a runtime error rather than a schema violation caught before anything runs.

The release cadence is visible in the tags. v4.2.0 arrived in December 2024, v4.2.1 in January 2025, and v4.3.0 in May 2025. The last push to the default branch was on 2026-09-21, so work on master continues between releases. Note that the README itself does not document the configuration format at all; it defers to the documentation site and to the README inside each subdirectory.

Installing a master and running a first build

The README does not give install commands. It says to see the README in each subdirectory, so the packaging details live under master/ and worker/ rather than at the top level. What the top-level files do tell you is the supported path the maintainers use for their own development: the Makefile creates a virtualenv named .venv$(VENV_PY_VERSION) with virtualenv -p $(VENV_PY_VERSION), defaulting VENV_PY_VERSION to python3, and points PIP at that environment. On Windows it switches to python -m venv and a Scripts directory.

That is the developer setup, not a deployment recipe. Treat it as the shape of the environment Buildbot expects: a Python virtualenv per component, with the master and the worker installed separately.

make virtualenv
make docs

The first target builds the virtualenv the Makefile defines; the second builds the documentation and prints the path to the generated HTML, which is where the configuration reference actually lives. If you are evaluating Buildbot, building the docs locally is a reasonable first move, because the README will not answer configuration questions.

For a container deployment, the repository ships Dockerfile.master at the top level, and requirements-master-docker-extras.txt alongside it, so the master image has an extra requirements file beyond the base master requirements. The README does not document the image's ports, volumes or environment variables, and I will not guess at them. Read Dockerfile.master before you build it.

A first real use is therefore: install the master, install a worker on a second machine, point the worker at the master, and define one build step. The repository does not show that configuration, so the exact keys belong in the documentation under master/docs, not in this article.

Where Buildbot is the wrong choice

The strongest argument against Buildbot is operational surface area. You are running a master process, a database, one or more workers, and a set of web packages, and you upgrade all of them. The repository's own file list shows the breadth: separate requirements files for the CI environment, the database, the docs, the worker, pyinstaller, and the Docker extras. Each of those is a thing that can drift out of sync with the others.

The GPL-2.0 licence is the second constraint, and it is a real one for some organisations. Buildbot is not offered under a permissive licence, so if your legal position requires permissive terms for infrastructure you redistribute or embed, this is not the project for that use. This is a description of the licence, not legal advice; talk to whoever handles licensing where you work.

Third, if your team wants the pipeline to live in the repository next to the code and be reviewed as a document, Buildbot's Python configuration cuts against that. It is more expressive and less scannable. For a project with one build matrix and a handful of steps, that expressiveness buys nothing and the setup cost is paid in full.

Finally, the README is thin. It is an index of components and a pointer to buildbot.net. Anyone who needs to evaluate Buildbot from the repository alone will not get far; the documentation site and the per-directory READMEs carry the actual instructions. That is a normal arrangement for a project this size, but it means the repository is not a self-contained onboarding path.

Buildbot against Jenkins and the hosted CI services

The comparisons people search for are Jenkins, GitLab CI and GitHub Actions, and the differences are structural rather than feature-level.

Jenkins is the closest relative. Both are self-hosted servers where you install agents on machines you own. The split differs in emphasis: Buildbot separates the master package from the worker package as distinct installable Python distributions, with their own requirements files in this repository, and its configuration is Python objects. Jenkins configuration is conventionally done through its web UI and plugin ecosystem, with pipeline definitions as a separate scripting layer. If you want to configure the server by clicking, Buildbot is not that.

GitLab CI and GitHub Actions invert the model. The pipeline is a file in the repository, and the provider supplies the runners. You trade control of the machines for not having to run any. Buildbot sits on the other side of that trade entirely: nothing about it assumes a hosting provider, and nothing about it provisions machines for you.

A practical way to decide: if the reason you are looking at Buildbot is that your build targets hardware the hosted providers do not offer, the master and worker split is the feature you want. If the reason is cost or a preference for open source, a hosted provider with self-hosted runners may get you there with less to operate.

Maintenance, releases and upgrade cost

Buildbot is not archived, and the last push to the default branch was on 2026-09-21. The release history shows v4.2.0 in December 2024, v4.2.1 in January 2025 and v4.3.0 in May 2025. Between those tags the repository keeps moving, so master and the latest release are not the same thing, and installing from master means tracking unreleased changes.

The upgrade cost is concentrated in the version pairing between master and worker. They are separate packages with separate requirements files, and a master that expects a newer worker protocol than the worker you deployed is a compatibility problem you have to plan around. Pin both, and upgrade them together.

The release notes are generated, not hand-written in the repository root. The pyproject.toml configures towncrier with package = "buildbot", package_dir = "master", directory = "newsfragments", and filename = "master/docs/relnotes/index.rst". So the changelog lives in the documentation tree, and contributors add entries as newsfragments rather than editing a changelog file. If you want to know what changed between two versions, read master/docs/relnotes/index.rst, not the README.

The licence is GPL-2.0, as stated in the repository. For internal use as a CI server this is normally unremarkable, but the copyleft terms matter if you plan to distribute a modified Buildbot or bundle it into something you ship. That is a question for your own legal review, not something this article can settle.

Editorial conclusion

Adopt Buildbot when you need a CI server that runs on your own machines and you accept that the master, the workers and the web UI are three things you configure and upgrade yourself. Do not adopt it if you want a hosted service that provisions runners for you, or if a single YAML file checked into the repository is the whole configuration model you want. Before committing, verify the Python version and dependency set the current master branch expects, check whether the worker package you would install matches the master release you plan to run, and read the release notes for the version you pick rather than the README, which is an index of components and points at the docs for everything else.

Frequently asked questions

Official sources

1. buildbot/buildbot on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases