tjh.dev
nixpkgs mirror (for testing)
github.com/NixOS/nixpkgs
nix
1# CI support files
2
3This directory contains files to support CI, such as [GitHub Actions](https://github.com/NixOS/nixpkgs/tree/master/.github/workflows) and [Ofborg](https://github.com/nixos/ofborg).
4This is in contrast with [`maintainers/scripts`](../maintainers/scripts) which is for human use instead.
5
6## Pinned Nixpkgs
7
8CI may need certain packages from Nixpkgs.
9In order to ensure that the needed packages are generally available without building, [`pinned.json`](./pinned.json) contains a pinned Nixpkgs version tested by Hydra.
10
11Run [`update-pinned.sh`](./update-pinned.sh) to update it.
12
13## GitHub specific code
14
15Some of the code is specific to GitHub.
16This code is currently spread out over multiple places and written in both Bash and JavaScript.
17The goal is to eventually have all GitHub specific code in `ci/github-script` and written in JavaScript via `actions/github-script`.
18A lot of code has already been migrated, but some Bash code still remains.
19New CI features need to be introduced in JavaScript, not Bash.
20
21## Nixpkgs merge bot
22
23The Nixpkgs merge bot empowers package maintainers by enabling them to merge PRs related to their own packages.
24It serves as a bridge for maintainers to quickly respond to user feedback, facilitating a more self-reliant approach.
25Especially when considering there are roughly 20 maintainers for every committer, this bot is a game-changer.
26
27Following [RFC 172], the merge bot was originally implemented as a [python webapp](https://github.com/NixOS/nixpkgs-merge-bot), which has now been integrated into [`ci/github-script/bot.js`](./github-script/bot.js) and [`ci/github-script/merge.js`](./github-script/merge.js).
28
29### Using the merge bot
30
31To merge a PR, maintainers can simply comment:
32```gfm
33@NixOS/nixpkgs-merge-bot merge
34```
35
36The next time the bot runs it will verify the below constraints, then (if satisfied) merge the PR.
37
38The merge bot will reference [#306934](https://github.com/NixOS/nixpkgs/issues/306934) on PRs it merges successfully, [#305350](https://github.com/NixOS/nixpkgs/issues/305350) for unsuccessful attempts, or [#371492](https://github.com/NixOS/nixpkgs/issues/371492) if an error occurs.
39These issues effectively list PRs the merge bot has interacted with.
40
41### Merge bot constraints
42
43To ensure security and a focused utility, the bot adheres to specific limitations:
44
45- The PR targets one of the [development branches](#branch-classification).
46- The PR only touches files of packages located under `pkgs/by-name/*`.
47- The PR is either:
48 - approved by a [committer][@NixOS/nixpkgs-committers].
49 - backported via label.
50 - opened by a [committer][@NixOS/nixpkgs-committers].
51 - opened by [@r-ryantm](https://nix-community.github.io/nixpkgs-update/r-ryantm/).
52- The user attempting to merge is a member of [@NixOS/nixpkgs-maintainers].
53- The user attempting to merge is a maintainer of all packages touched by the PR.
54
55### Approving merge bot changes
56
57Changes to the bot can usually be approved by the [@NixOS/nixpkgs-ci] team, as with other CI changes.
58However, additional acknowledgement from the [@NixOS/nixpkgs-core] team is required for changes to what the merge bot will merge, who is eligible to use the merge bot, or similar changes in scope.
59
60## `ci/nixpkgs-vet.sh BASE_BRANCH [REPOSITORY]`
61
62Runs the [`nixpkgs-vet` tool](https://github.com/NixOS/nixpkgs-vet) on the HEAD commit, closely matching what CI does.
63This can't do exactly the same as CI, because CI needs to rely on GitHub's server-side Git history to compute the mergeability of PRs before the check can be started.
64In turn, when contributors are running this tool locally, we don't want to have to push commits to test them, and we can also rely on the local Git history to do the mergeability check.
65
66Arguments:
67
68- `BASE_BRANCH`: The base branch to use, e.g. master or release-24.05
69- `REPOSITORY`: The repository from which to fetch the base branch.
70 Defaults to <https://github.com/NixOS/nixpkgs.git>.
71
72# Branch classification
73
74For the purposes of CI, branches in the NixOS/nixpkgs repository are classified as follows:
75
76- **Channel** branches
77 - `nixos-` or `nixpkgs-` prefix
78 - Are only updated from `master` or `release-` branches, when hydra passes.
79 - Otherwise not worked on, Pull Requests are not allowed.
80 - Long-lived, no deletion, no force push.
81- **Primary development** branches
82 - `release-` prefix and `master`
83 - Pull Requests required.
84 - Long-lived, no deletion, no force push.
85- **Secondary development** branches
86 - `staging-` prefix and `haskell-updates`
87 - Pull Requests normally required, except when merging development branches into each other.
88 - Long-lived, no deletion, no force push.
89- **Work-In-Progress** branches
90 - `backport-`, `revert-` and `wip-` prefixes.
91 - Deprecated: All other branches, not matched by channel/development.
92 - Pull Requests are optional.
93 - Short-lived, force push allowed, deleted after merge.
94
95Some branches also have a version component, which is either `unstable` or `YY.MM`.
96
97`ci/supportedBranches.js` is a script imported by CI to classify the base and head branches of a Pull Request.
98This classification will then be used to skip certain jobs.
99This script can also be run locally to print basic test cases.
100
101
102[@NixOS/nixpkgs-maintainers]: https://github.com/orgs/NixOS/teams/nixpkgs-maintainers
103[@NixOS/nixpkgs-committers]: https://github.com/orgs/NixOS/teams/nixpkgs-committers
104[@NixOS/nixpkgs-ci]: https://github.com/orgs/NixOS/teams/nixpkgs-ci
105[@NixOS/nixpkgs-core]: https://github.com/orgs/NixOS/teams/nixpkgs-core
106[RFC 172]: https://github.com/NixOS/rfcs/pull/172