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/

0 files changed, 0 insertions, 0 deletions