From ce8c42d995342ee602c658d688be86b25428743d Mon Sep 17 00:00:00 2001 From: Wolfgang Walther Date: Mon, 20 Oct 2025 21:52:04 +0200 Subject: [PATCH] ci/README: add github-script policy Over the last couple of months we have been migrating a lot of the old bash code to JavaScript, which is supported in GitHub Actions via `actions/github-script`. This change documents a "manual ratchet check" for this migration - new code should only be introduced as JavaScript and not as Bash. This will help us to eventually succeed with the migration and ensure quality and maintainability. We are migrating to JavaScript, because: 1. Using JavaScript is GitHub's [recommendation] against injection attacks. Using `actions/github-script` has first-class support for the event context and does not require to resort back to environment variables in most cases. When environment variables need to be used, these are accessed via `process.env`, without a risk for accidental injections. Using `actions/github-script` is also recommended in a recent [survey] of open source supply chain compromises: > Finally, since two out of three compromises were due to shell injection, > it might be safer to use a proper programming language, like JavaScript > with actions/github-script, or any other language accessing the context > via environment variables instead of YAML interpolation. 2. Handling even environment variables in Bash safely is almost impossible. For example arithmetic expressions cause arbitrary code execution vulnerabilities. While a lot of contributors are somehwat familiar writing Bash code for builders, writing *safe* Bash code for CI is a very different matter. Few people, if any, know how to do this. 3. GitHub Action's security model is quite unintuitive and even if some code runs with trusted inputs today, it may later be used in a more exposed context. Instead of making judgement calls about language choice case by case, a clear policy helps writing things defensively from the beginning. 4. We have developed a framework around our github-script based tools in `ci/github-script`. This provides a local `nix-shell` environment with the right dependencies and a local runner for these scripts for quick testing, debugging and development. No matter, whether you're developing a new feature, fixing bugs or reviewing a PR - this allows much quicker verification of the scripts, *without* running everything in a fork or test organization. 5. This framework also provides helpers for challenges that come up with GHA. One example is rate-limiting, where we have a helper script that will handle all rate-limiting needs for us, preventing us from running out of API calls and thus breaking CI entirely. We can only use these tools consistently, if we consistently use JavaScript code. 6. Using JavaScript allows us to handle JSON natively. Using `octokit/rest.js` provides first-class integration with GitHub's API. Together, this makes these scripts much more maintainable than resorting to `gh` and `jq`. [recommendation]: https://docs.github.com/en/actions/reference/security/secure-use#use-an-action-instead-of-an-inline-script [survey]: https://words.filippo.io/compromise-survey/ --- ci/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/ci/README.md b/ci/README.md index 797f231aea62..389ef59f57b9 100644 --- a/ci/README.md +++ b/ci/README.md @@ -10,6 +10,14 @@ In order to ensure that the needed packages are generally available without buil Run [`update-pinned.sh`](./update-pinned.sh) to update it. +## GitHub specific code + +Some of the code is specific to GitHub. +This code is currently spread out over multiple places and written in both Bash and JavaScript. +The goal is to eventually have all GitHub specific code in `ci/github-script` and written in JavaScript via `actions/github-script`. +A lot of code has already been migrated, but some Bash code still remains. +New CI features need to be introduced in JavaScript, not Bash. + ## `ci/nixpkgs-vet.sh BASE_BRANCH [REPOSITORY]` Runs the [`nixpkgs-vet` tool](https://github.com/NixOS/nixpkgs-vet) on the HEAD commit, closely matching what CI does.