Buildbot-nix is a NixOS module designed to integrate Buildbot, a continuous integration (CI) framework, into the Nix ecosystem. This module is under active development, and while it's generally stable and widely used, please be aware that some APIs may change over time.
- Fast, Parallel evaluation using nix-eval-jobs
- Github integration:
- Login with GitHub to control builds
- CI status notification in pull requests and on the default branch
- All builds share the same nix store for speed
- The last attribute of a build is protected from garbage collection
- Build matrix based on
.#checksattributes - No arbitrary code runs outside of the Nix sandbox
- experimental hercules-ci effect to run impure CI steps i.e. deploying NixOS
To set up Buildbot using Buildbot-nix, you can start by exploring the provided examples:
- Check out the basic setup in example.
- Learn about configuring the Buildbot master in master module.
- Understand how to set up a Buildbot worker in worker module.
Additionally, you can find real-world examples at the end of this document.
Buildbot masters and workers can be deployed either on the same machine or on separate machines. To support multiple architectures, configure them as nix remote builders. For a practical NixOS example, see this remote builder configuration.
The module applies custom patches that only apply to buildbot > 4.0.0. To use buildbot-nix with NixOS 24.05, you should therefore not override the nixpkgs input to your own stable version of buildbot-nix and leave it to the default instead that is set to nixos-unstable-small.
So instead of using this in your flake
inputs = {
buildbot-nix.url = "github:nix-community/buildbot-nix";
buildbot-nix.inputs.nixpkgs.follows = "nixpkgs";
};
Just use:
inputs = {
buildbot-nix.url = "github:nix-community/buildbot-nix";
};
An alternative is to point nixpkgs to your own version of nixpkgs-unstable in case you are already using it elsewhere.
Buildbot-nix automatically triggers builds for your project under these conditions:
- When a pull request is opened.
- When a commit is pushed to the default git branch.
It does this by evaluating the .#checks attribute of your project's flake in
parallel. Each attribute found results in a separate build step. You can test
these builds locally using nix flake check -L or
nix-fast-build.
If you need to build other parts of your flake, such as packages or NixOS
machines, you should re-export these into the .#checks output. Here are two
examples to guide you:
- Using flake-parts.
- A plain flake example.
At the moment buildbot-nix offers two access modes, public and
fullyPrivate. public is the default and gives read-only access to all of
buildbot, including builds, logs and builders. For read-write access,
authentication is still needed, this is controlled by the authBackend option.
fullyPrivate will hide buildbot behind oauth2-proxy which protects the whole
buildbot instance. buildbot fetches the currently authenticated user from
oauth2-proxy so the same admin, organisation rules apply.
fullyPrivate acccess mode is a workaround as buildbot does not support hiding
information natively as now.
For some actions a login is required. This login can either be based on GitHub
or on Gitea (more logins may follow). The backend is set by the
services.buildbot-nix.master.authBackend NixOS option ("gitea"/"github",
"github" by default).
We have the following two roles:
- Admins:
- The list of admin usernames is hard-coded in the NixOS configuration.
- admins can reload the project list
- Organisation member:
- All member of the organisation where this repository is located
- They can restart builds
This is the preferred option to setup buildbot-nix for GitHub.
To integrate with GitHub using app authentication:
- GitHub App:
- Create a new GitHub app by navigating to
https://github.com/settings/apps/newfor single-user installations orhttps://github.com/organizations/<org>/settings/apps/newfor organisations where<org>is the name of your GitHub organizaction. - GitHub App Name: "buildbox-nix "
- Homepage URL:
https://buildbot.<your-domain> - Callback URL:
https://buildbot.<your-domain>/auth/login. - Disable the Webhook
- Repository Permissions:
- Contents: Read-only
- Commit statuses: Read and write
- Metadata: Read-only
- Webhooks: Read and write
- Organisation Permissions (only if you create this app for an organisation):
- Members: Read-only
- Create a new GitHub app by navigating to
- GitHub App private key: Get the app private key and app ID from GitHub,
configure using the buildbot-nix NixOS module.
- Set
services.buildbot-nix.master.github.authType.app.id = <your-github-id>; - Set
services.buildbot-nix.master.github.authType.app.secretKeyFile = "/path/to.pem";
- Set
- Install App: Install the app for an organization or specific user.
- Refresh GitHub Projects: Currently buildbot-nix doesn't respond to changes (new repositories or installations) automatically, it is therefore necessary to manually trigger a reload or wait for the next periodic reload.
To integrate with GitHub using legacy token authentication:
- GitHub Token: Obtain a GitHub token with
admin:repo_hookandrepopermissions. For GitHub organizations, it's advisable to create a separate GitHub user for managing repository webhooks.
- GitHub App: Set up a GitHub app for Buildbot to enable GitHub user authentication on the Buildbot dashboard. (can be the same as for GitHub App auth)
- OAuth Credentials: After installing the app, generate OAuth credentials
and configure them in the buildbot-nix NixOS module. Set the callback url to
https://<your-domain>/auth/login.
Afterwards add the configured github topic to every project that should build with buildbot-nix. Notice that the buildbot user needs to have admin access to this repository because it needs to install a webhook.
To integrate with Gitea
- Gitea Token Obtain a Gitea token with the following permissions
write:repositoryandwrite:userpermission. For Gitea organizations, it's advisable to create a separate Gitea user. Buildbot-nix will use this token to automatically setup a webhook in the repository. - Gitea App: (optional). This is optional, when using GitHub as the
authentication backend for buildbot. Set up a OAuth2 app for Buildbot in the
Applications section. This can be done in the global "Site adminstration"
settings (only available for admins) or in a Gitea organisation or in your
personal settings. As redirect url set
https://buildbot.your-buildbot-domain.com/auth/login, wherebuildbot.your-buildbot-domain.comshould be replaced with the actual domain that your buildbot is running on.
Afterwards add the configured gitea topic to every project that should build with buildbot-nix. Notice that the buildbot user needs to have repository write access to this repository because it needs to install a webhook in the repository.
To enable fully private mode, set acessMode.fullyPrivate to an attrset
containing the required options for fully private use, refer to the examples and
module implementation (nix/master.nix).
This access mode honors the admins option in addition to the
accessMode.fullyPrivate.organisations option. To allow access from certain
organisations, you must explicitly list them.
If you've set authBackend previously, unset it, or you will get an error about
a conflicting definitions. fullyPrivate requires the authBackend to be set
to basichttpauth to function (this is handled by the module, which is why you
can leave it unset). For a concrete example please refer to
fully-private-github
Currently buildbot-nix will look for a file named buildbot-nix.toml in the
root of whichever branch it's currently evaluating, parse it as TOML and apply
the configuration specified. The following table illustrates the supported
options.
| key | type | description | default | example | |
|---|---|---|---|---|---|
| lock file | lock_file |
str |
dictates which lock file buildbot-nix will use when evaluating your flake |
flake.lock |
have multiple lockfiles, one for nixpkgs-stable, one for nixpkgs-unstable or by default pin an input to a private repo, but have a lockfile with that private repo replaced by a public repo for CI |
| attribute | attribute |
str |
which attribute in the flake to evaluate and build | checks |
using a different attribute, like hydraJobs |
To access the build results on other machines there are two options at the moment
You can set up a binary cache on your buildbot-worker machine to make its nix store accessible from other machines. Check out the README of the project, for an example configuration
Buildbot-nix also supports pushing packages to cachix. Check out the comment out example configuration in our repository.
Buildbot-nix does not have native support for pushing packages to attic yet. However it's possible to integrate run a systemd service as described in this example configuration. The systemd service watches for changes in the local buildbot-nix store and uploads the contents to the attic cache.
See flake.nix for an example and [https://docs.hercules-ci.com/hercules-ci/effects/] for documentation.
You can run hercules-effects locally using the buildbot-effects cli:
$ buildbot-effects --help
usage: buildbot-effects [-h] [--secrets SECRETS] [--rev REV] [--branch BRANCH] [--repo REPO] [--path PATH] {list,run,run-all} ...
Run effects from a hercules-ci flake
positional arguments:
{list,run,run-all} Command to run
list List available effects
run Run an effect
run-all Run all effects
options:
-h, --help show this help message and exit
--secrets SECRETS Path to a json file with secrets
--rev REV Git revision to use
--branch BRANCH Git branch to use
--repo REPO Git repo to prepend to be
--path PATH Path to the repository
Example from the buildbot-nix repository:
$ git clone github.com/nix-community/buildbot-nix
$ cd buildbot-nix$ nix run github:nix-community/buildbot-nix#buildbot-effects -- list
[
"deploy"
]$ nix run github:nix-community/buildbot-nix#buildbot-effects -- --branch main run deploy
{branch:main,rev:5d2e0af1cfccfc209b893b89392cf80f5640d936,tag:null}
Hello, world!The lix overlay overrides nix-eval-jobs with a version that doesn't work with buildbot-nix because of missing features and therefore cannot be used together with the buildbot-nix module.
Possible workaround: Don't use the overlay and only set the
nix.package = pkgs.lix; NixOS option.
See Buildbot-nix in action in these deployments:
The following instances run on GitHub:
- Nix-community infra: Configuration | Instance
- Mic92's dotfiles: Configuration | Instance
- Technical University Munich: Configuration | Instance
- Numtide: Instance
- Ngi0: Instance
The following instances integrated with Gitea:
- Clan infra: Configuration | Instance
We have a matrix channel at buildbot-nix.
For commercial support, please contact Mic92 at joerg@thalheim.io or reach out to Numtide.