ci/README.md

   1 # CI support files
   2
   3 This 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).
   4 This is in contrast with [`maintainers/scripts`](../maintainers/scripts) which is for human use instead.
   5
   6 ## Pinned Nixpkgs
   7
   8 CI may need certain packages from Nixpkgs.
   9 In order to ensure that the needed packages are generally available without building,
  10 [`pinned-nixpkgs.json`](./pinned-nixpkgs.json) contains a pinned Nixpkgs version tested by Hydra.
  11
  12 Run [`update-pinned-nixpkgs.sh`](./update-pinned-nixpkgs.sh) to update it.
  13
  14 ## `ci/nixpkgs-vet.sh BASE_BRANCH [REPOSITORY]`
  15
  16 Runs the [`nixpkgs-vet` tool](https://github.com/NixOS/nixpkgs-vet) on the HEAD commit, closely matching what CI does. This 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.
  17 In 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.
  18
  19 Arguments:
  20
  21 - `BASE_BRANCH`: The base branch to use, e.g. master or release-24.05
  22 - `REPOSITORY`: The repository from which to fetch the base branch. Defaults to <https://github.com/NixOS/nixpkgs.git>.
  23
  24 ## `ci/nixpkgs-vet`
  25
  26 This directory contains scripts and files used and related to [`nixpkgs-vet`](https://github.com/NixOS/nixpkgs-vet/), which the CI uses to implement `pkgs/by-name` checks, along with many other Nixpkgs architecture rules.
  27 See also the [CI GitHub Action](../.github/workflows/nixpkgs-vet.yml).
  28
  29 ## `ci/nixpkgs-vet/update-pinned-tool.sh`
  30
  31 Updates the pinned [`nixpkgs-vet` tool](https://github.com/NixOS/nixpkgs-vet) in [`ci/nixpkgs-vet/pinned-version.txt`](./nixpkgs-vet/pinned-version.txt) to the latest [release](https://github.com/NixOS/nixpkgs-vet/releases).
  32
  33 Each release contains a pre-built `x86_64-linux` version of the tool which is used by CI.
  34
  35 This script currently needs to be called manually when the CI tooling needs to be updated.
  36
  37 Why not just build the tooling right from the PRs Nixpkgs version?
  38
  39 - Because it allows CI to check all PRs, even if they would break the CI tooling.
  40 - Because it makes the CI check very fast, since no Nix builds need to be done, even for mass rebuilds.
  41 - Because it improves security, since we don't have to build potentially untrusted code from PRs.
  42   The tool only needs a very minimal Nix evaluation at runtime, which can work with [readonly-mode](https://nixos.org/manual/nix/stable/command-ref/opt-common.html#opt-readonly-mode) and [restrict-eval](https://nixos.org/manual/nix/stable/command-ref/conf-file.html#conf-restrict-eval).
  43
  44 ## `get-merge-commit.sh GITHUB_REPO PR_NUMBER`
  45
  46 Check whether a PR is mergeable and return the test merge commit as
  47 [computed by GitHub](https://docs.github.com/en/rest/guides/using-the-rest-api-to-interact-with-your-git-database?apiVersion=2022-11-28#checking-mergeability-of-pull-requests).
  48
  49 Arguments:
  50 - `GITHUB_REPO`: The repository of the PR, e.g. `NixOS/nixpkgs`
  51 - `PR_NUMBER`: The PR number, e.g. `1234`
  52
  53 Exit codes:
  54 - 0: The PR can be merged, the test merge commit hash is returned on stdout
  55 - 1: The PR cannot be merged because it's not open anymore
  56 - 2: The PR cannot be merged because it has a merge conflict
  57 - 3: The merge commit isn't being computed, GitHub is likely having internal issues, unknown if the PR is mergeable
  58
  59 ### Usage
  60
  61 This script can be used in GitHub Actions workflows as follows:
  62
  63 ```yaml
  64 on: pull_request_target
  65
  66 # We need a token to query the API, but it doesn't need any special permissions
  67 permissions: {}
  68
  69 jobs:
  70   build:
  71     name: Build
  72     runs-on: ubuntu-latest
  73     steps:
  74       # Important: Because of `pull_request_target`, this doesn't check out the PR,
  75       # but rather the base branch of the PR, which is needed so we don't run untrusted code
  76       - uses: actions/checkout@<VERSION>
  77         with:
  78           path: base
  79           sparse-checkout: ci
  80       - name: Resolving the merge commit
  81         env:
  82           GH_TOKEN: ${{ github.token }}
  83         run: |
  84           if mergedSha=$(base/ci/get-merge-commit.sh ${{ github.repository }} ${{ github.event.number }}); then
  85             echo "Checking the merge commit $mergedSha"
  86             echo "mergedSha=$mergedSha" >> "$GITHUB_ENV"
  87           else
  88             # Skipping so that no notifications are sent
  89             echo "Skipping the rest..."
  90           fi
  91           rm -rf base
  92       - uses: actions/checkout@<VERSION>
  93         # Add this to _all_ subsequent steps to skip them
  94         if: env.mergedSha
  95         with:
  96           ref: ${{ env.mergedSha }}
  97       - ...
  98 ```