doc: Detail configuration of hosted CI runners
What the developer wrote
Authored by will
doc: Detail configuration of hosted CI runners
What changed, and why it matters
This commit only updates documentation in the CI (continuous integration) README file. It explains how to set up paid Cirrus Runners for faster automated testing and how forks can use free GitHub runners. There are no code changes and no security-relevant behavior changes.
No security action required. Review as normal documentation change.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff is a pure Markdown documentation edit in ci/README.md. It restructures headings, adds a ‘Configuring a repository for CI’ section describing Cirrus Runners registration, GitHub app installation, runner group permissions, permitted GitHub Actions, and fork behavior. No executable code, configuration defaults, secrets, or cryptographic logic were modified.
Changed components
ci/README.mdInspect captured patch +28 / −4
diff --git a/ci/README.md b/ci/README.md
index 377aae7f..81e048ce 100644
--- a/ci/README.md
+++ b/ci/README.md
@@ -1,8 +1,8 @@
-## CI Scripts
+# CI Scripts
This directory contains scripts for each build step in each build stage.
-### Running a Stage Locally
+## Running a Stage Locally
Be aware that the tests will be built and run in-place, so please run at your own risk.
If the repository is not a fresh git clone, you might have to clean files from previous builds or test runs first.
@@ -27,7 +27,7 @@ with a specific configuration,
env -i HOME="$HOME" PATH="$PATH" USER="$USER" bash -c 'FILE_ENV="./ci/test/00_setup_env_arm.sh" ./ci/test_run_all.sh'
```
-### Configurations
+## Configurations
The test files (`FILE_ENV`) are constructed to test a wide range of
configurations, rather than a single pass/fail. This helps to catch build
@@ -49,8 +49,32 @@ env -i HOME="$HOME" PATH="$PATH" USER="$USER" bash -c 'MAKEJOBS="-j1" FILE_ENV="
The files starting with `0n` (`n` greater than 0) are the scripts that are run
in order.
-### Cache
+## Cache
In order to avoid rebuilding all dependencies for each build, the binaries are
cached and reused when possible. Changes in the dependency-generator will
trigger cache-invalidation and rebuilds as necessary.
+
+## Configuring a repository for CI
+
+### Primary repository
+
+To configure the primary repository, follow these steps:
+
+1. Register with [Cirrus Runners](https://cirrus-runners.app/) and purchase runners.
+2. Install the Cirrus Runners GitHub app against the GitHub organization.
+3. Enable organisation-level runners to be used in public repositories:
+ 1. `Org settings -> Actions -> Runner Groups -> Default -> Allow public repos`
+4. Permit the following actions to run:
+ 1. cirruslabs/cache/restore@\*
+ 1. cirruslabs/cache/save@\*
+ 1. docker/setup-buildx-action@\*
+ 1. actions/github-script@\*
+
+### Forked repositories
+
+When used in a fork the CI will run on GitHub's free hosted runners by default.
+In this case, due to GitHub's 10GB-per-repo cache size limitations caches will be frequently evicted and missed, but the workflows will run (slowly).
+
+It is also possible to use your own Cirrus Runners in your own fork with an appropriate patch to the `REPO_USE_CIRRUS_RUNNERS` variable in ../.github/workflows/ci.yml
+NB that Cirrus Runners only work at an organisation level, therefore in order to use your own Cirrus Runners, *the fork must be within your own organisation*.
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.