Improve readme
Improve readme
This commit is contained in:
Jörg Thalheim
mergify[bot]
parent
f56e43267d
commit
1df661d6fd
84
README.md
84
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)
|
||||
|
|
|
|||
|
|
@ -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";
|
||||
|
|
|
|||
Loading…
Reference in a new issue