Go to file
github-actions[bot] e9a3849417 flake.lock: Update
Flake lock file updates:

• Updated input 'flake-parts':
    'github:hercules-ci/flake-parts/4d34ce6412bc450b1d4208c953dc97c7fc764f1a' (2024-05-01)
  → 'github:hercules-ci/flake-parts/e5d10a24b66c3ea8f150e47dfdb0416ab7c3390e' (2024-05-02)
• Updated input 'nixpkgs':
    'github:Nixos/nixpkgs/23cc2b1f071baee1853de7d93df6167bdfe57aa6' (2024-05-01)
  → 'github:Nixos/nixpkgs/9a22fecda3caa5fb5ae716fab63c5b8f0b7e1060' (2024-05-04)
2024-05-05 01:45:20 +00:00
.github Bump cachix/install-nix-action from 25 to 26 2024-03-11 01:57:51 +00:00
bin add buildbot-effects 2023-12-26 21:54:20 +01:00
buildbot_effects fix new linting errors 2023-12-26 22:36:40 +01:00
buildbot_nix gitea: don't drop pull request events 2024-05-03 20:36:17 +02:00
examples README: also link to clan infra 2024-05-04 21:57:28 +00:00
nix make it possible to disable github 2024-04-30 17:32:40 +02:00
.gitignore also create webhooks automatically 2023-10-12 17:50:43 +02:00
.mergify.yml fix mergify configuration 2024-04-23 16:11:20 +02:00
default.nix add buildbot_nix as a python package to buildbot 2023-10-31 11:35:35 +01:00
flake.lock flake.lock: Update 2024-05-05 01:45:20 +00:00
flake.nix devshell: add mypy + ruff 2023-12-26 19:50:34 +01:00
pyproject.toml do merges locally 2024-04-06 18:54:58 +02:00
README.md gitea: mention webhook 2024-05-04 21:57:28 +00:00

Buildbot-nix

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.

Getting Started with Buildbot Setup

To set up Buildbot using Buildbot-nix, you can start by exploring the provided examples:

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.

Using Buildbot in Your Project

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:

Authentication backend

At the moment all projects are visible without authentication.

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.

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

Integration with GitHub

To integrate with GitHub:

  1. GitHub Token: Obtain a GitHub token with admin:repo_hook and repo permissions. For GitHub organizations, it's advisable to create a separate GitHub user for managing repository webhooks.

Optional when using GitHub login

  1. GitHub App: Set up a GitHub app for Buildbot to enable GitHub user authentication on the Buildbot dashboard.
  2. 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.

Integration with Gitea

To integrate with Gitea

  1. Gitea Token Obtain a Gitea token with the following permissions write:repository and write:user permission. 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.
  2. 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, where buildbot.your-buildbot-domain.com should 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.

Binary caches

To access the build results on other machines there are two options at the moment

Local binary cache (harmonia)

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

Cachix

Buildbot-nix also supports pushing packages to cachix. Check out the comment out example configuration in our repository.

Real-World Deployments

See Buildbot-nix in action in these deployments:

The following instances run on GitHub:

The following instances integrated with Gitea: