From 1df661d6fd8ae64f4015000f0f86bad5eaff60da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= Date: Sun, 24 Dec 2023 08:12:42 +0100 Subject: [PATCH] Improve readme Improve readme --- README.md | 84 ++++++++++++++++++++++++++++++++++---------- examples/default.nix | 4 +++ 2 files changed, 70 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 36e8ca6..81dbdcd 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,78 @@ # Buildbot-nix -A nixos module to make [buildbot](https://www.buildbot.net/) a proper Nix-CI. +Buildbot-nix is a NixOS module designed to integrate +[Buildbot](https://www.buildbot.net/), 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. -For an example checkout the [example](./examples/default.nix) and the module -descriptions for [master](./nix/master.nix) and [worker](./nix/worker.nix). +## Getting Started with Buildbot Setup -This project is still in early stage and many APIs might change over time. +To set up Buildbot using Buildbot-nix, you can start by exploring the provided +examples: -## Github +- Check out the basic setup in [example](./examples/default.nix). +- Learn about configuring the Buildbot master in + [master module](./nix/master.nix). +- Understand how to set up a Buildbot worker in + [worker module](./nix/worker.nix). -We currently primarly support Github as a platform but we are also looking into -supporting other CIs such as gitea. +Additionally, you can find real-world examples at the end of this document. -Buildbot requires a GitHub app, to allow login for GitHub users to its -dashboard. After installing the app, create oauth credentials and set them in -the buildbot-nix nixos module. +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](https://nixos.org/manual/nix/stable/advanced-topics/distributed-builds). +For a practical NixOS example, see +[this remote builder configuration](https://github.com/Mic92/dotfiles/blob/main/nixos/eve/modules/remote-builder.nix). -Furthermore buildbot requires a github token with the following permissions: +## Using Buildbot in Your Project -- `admin:repo_hook`, `repo` +Buildbot-nix automatically triggers builds for your project under these +conditions: -For github organisations it's recommend to create an additional GitHub user for -that. +- When a pull request is opened. +- When a commit is pushed to the default git branch. -## Real-worlds deployments +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](https://github.com/Mic92/nix-fast-build). -- [Nix-community infra](https://github.com/nix-community/infra/tree/master/modules/nixos) -- [Mic92's dotfiles](https://github.com/Mic92/dotfiles/blob/main/nixos/eve/modules/buildbot.nix) -- [Technical University Munich](https://github.com/TUM-DSE/doctor-cluster-config/tree/master/modules/buildbot) +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](https://github.com/Mic92/dotfiles/blob/10890601a02f843b49fe686d7bc19cb66a04e3d7/flake.nix#L139). +- A + [plain flake example](https://github.com/nix-community/nixos-images/blob/56b52791312edeade1e6bd853ce56c778f363d50/flake.nix#L53). + +### Integration with GitHub + +Buildbot-nix primarily supports GitHub, with plans to extend support to other +platforms like Gitea. + +To integrate with GitHub: + +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. +3. **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. + +### Real-World Deployments + +See Buildbot-nix in action in these deployments: + +- **Nix-community infra**: + [Configuration](https://github.com/nix-community/infra/tree/master/modules/nixos) + | [Instance](https://buildbot.nix-community.org/) +- **Mic92's dotfiles**: + [Configuration](https://github.com/Mic92/dotfiles/blob/main/nixos/eve/modules/buildbot.nix) + | [Instance](https://buildbot.thalheim.io/) +- **Technical University Munich**: + [Configuration](https://github.com/TUM-DSE/doctor-cluster-config/tree/master/modules/buildbot) + | [Instance](https://buildbot.dse.in.tum.de/) +- **Numtide**: [Instance](https://buildbot.numtide.com) diff --git a/examples/default.nix b/examples/default.nix index bb0598e..f9fb42e 100644 --- a/examples/default.nix +++ b/examples/default.nix @@ -35,6 +35,10 @@ in oauthId = "aaaaaaaaaaaaaaaaaaaa"; user = "mic92-buildbot"; admins = [ "Mic92" ]; + # All github projects with this topic will be added to buildbot. + # One can trigger a project scan by visiting the Builds -> Builders page and looking for the "reload-github-project" builder. + # This builder has a "Update Github Projects" button that everyone in the github organization can use. + topic = "buildbot-mic92"; }; # optional expose latest store path as text file # outputsPath = "/var/www/buildbot/nix-outputs";