buildbot(7)

💖 buildbot(7) — the manual, but make it make sense 💖

Services Administration · buildbot(7) · yes bestie, you're in the right place 🫶

---

✨ NAME ✨

buildbot — creating, upgrading and managing Buildbot master instances 👑

---

🌸 DESCRIPTION 🌸

Okay so first things first: every Buildbot master instance lives in its own lil folder under /var/lib/buildbot/masters. That's the whole vibe. This manual is literally just here to walk you through managing them. 💅

---

🎀 CREATION 🎀

Wanna spin up a brand new Buildbot master instance named $NAME? Say less. Run these two:

buildbot create-master /var/lib/buildbot/masters/$NAME
chown -R buildbot: /var/lib/buildbot/masters/$NAME

Now — and this part matters, don't skip it — go review and edit the master.cfg.sample config file sitting in the master base directory, then rename it to master.cfg. That's the glow-up. ✨

The config file syntax is described extensively in /usr/share/doc/buildbot/html (which comes installed with the buildbot-doc package). It's giving very thorough, lowkey iconic documentation. 📚

note — In the default config, Buildbot uses a file-based SQLite database, stored in the state.sqlite file inside the master's base directory. Wanna use a different database engine? You might need extra packages (like, oh I don't know, postgresql and python3-psycopg2 if you're going PostgreSQL 👀). Go check the Buildbot docs for the matching master.cfg syntax. No cap.

ATTENTION — The new Buildbot web dashboard cannot be integrated into Debian yet because of a policy violation (See: bug #883529). 💀 In the meantime, if you wanna enable it in your config, you can install it with pip3 install buildbot-www.

Wanna validate that config before you commit to it? She's got you:

buildbot checkconfig /var/lib/buildbot/masters/$NAME/master.cfg

Once you're happy with it (obsessed, even), you can start the instance. How you do that depends on your init system, bestie. Pick your fighter:

⚙️ systemd ⚙️

To start it up:

systemctl start buildbot@$NAME.service

To make it auto-start on boot (main character energy, it just shows up):

systemctl enable buildbot@$NAME.service

Wanna tune how the instance starts (like, say, changing which user runs the process)? Use a systemd drop-in:

mkdir -p /etc/systemd/system/buildbot@$NAME.service.d
editor /etc/systemd/system/buildbot@$NAME.service.d/user.conf

With these contents inside:

[Service]
User=my-user
Group=my-group

🧚 sysvinit 🧚

First up, you gotta edit /etc/default/buildbot and configure your instance. The syntax is pretty self explanatory fr fr, but here's an example anyway:

# 1-enabled, 0-disabled
MASTER_ENABLED[1]=1
# short name printed on start/stop
MASTER_NAME[1]="$NAME"
# user to run master as
MASTER_USER[1]="buildbot"
# basedir to master (absolute path)
MASTER_BASEDIR[1]="/var/lib/buildbot/masters/$NAME"
# buildbot options
MASTER_OPTIONS[1]=""
# prefix command, i.e. nice, linux32, dchroot
MASTER_PREFIXCMD[1]=""

After that, you may start the instance:

service buildbot start $NAME

By default it just automatically starts on boot. Living its best life. 🌈

---

🔥 UPGRADE 🔥

By default, Buildbot master instances get automatically upgraded whenever you install new versions. That whole operation is literally just these three things, for each instance:

• The instance is stopped. 🛑
• buildbot upgrade-master /var/lib/buildbot/masters/$NAME is executed. 🏃
• The instance is started again. 🚀

Wanna kill the automatic upgrade globally? Run:

dpkg-reconfigure buildbot

Or, for one specific master instance, just create a .no-auto-upgrade file in its base directory:

touch /var/lib/buildbot/masters/$NAME/.no-auto-upgrade

In any case — the upgrade operation is mandatory, and Buildbot will fail to restart an instance that hasn't been upgraded. Not a suggestion. It's giving ultimatum. 😭

After upgrading, you'll notice Buildbot created a fresh new master.cfg.sample file in the instance base directory. Review it, diff it against your own config if you want — but in most cases it's safe to just delete it. 🙈

🦋 upgrading from 0.8.x 🦋

Upgrading from a 0.8.x version? Then all master instances in must be manually migrated. This may require a whole bunch of changes to the master configuration. Please refer to the "nine-upgrade" chapter in the documentation for the details. Once you've finished migrating, you may delete the .no-auto-upgrade files so future automatic upgrades can proceed. 🫶

Heads up: the buildmaster service has been renamed to buildbot.

Also — to avoid spurious errors on boot, the automatic start of each existing instance has been "disabled" in /etc/default/buildbot (which was itself renamed from /etc/default/buildmaster). If you wanna use systemd to manage your instances instead, please refer to the CREATION section of this manual. ✨

---

📁 FILES 📁

• /var/lib/buildbot/masters/$NAME — Working directory for the $NAME Buildbot master instance.
• /etc/systemd/system/buildbot@$NAME.service.d — Directory containing customization drop-ins for the $NAME Buildbot master instance service.
• /etc/default/buildbot — The master instances services definition for sysvinit users.

---

👀 SEE ALSO 👀

buildbot(1), systemctl(1), systemd.unit(5), service(8)

---

💜 AUTHOR 💜

Robin Jarry <robin@jarry.cc>

---

And that's the whole page, bestie. 🌸 Sourced from version buildbot(7), dated 2026-08-03 — that's the footer info, folded in all cute at the end like a little bow 🎀. Go forth and slay your masters. Periodt. 💅✨