From 9d771a7b27a4ea2f84ebcadcd02ebfa29c2f7867 Mon Sep 17 00:00:00 2001 From: aitrawog Date: Tue, 29 Sep 2026 02:53:29 +0200 Subject: [PATCH] docs: tailored README + AGENTS.md signpost (pod-github-runner) (#286) --- AGENTS.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 56 +++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 120 insertions(+), 4 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..11a849a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,68 @@ +# AGENTS.md — pod-github-runner + +Standalone candy repo for the `github-runner` candy — a GitHub Actions +self-hosted runner that builds CI jobs rootless inside a disposable box. The +candy lives in `charly.yml` at the repo root. + +Canonical files: + +- `charly.yml` — the `github-runner:` candy entity (description, `require`, + `distro`, `volume`, `env`, `env_accept`, `secret_accept`, `var`, `hook`, + `service`, `plan`) and its `skill:` entity. +- `.github/workflows/tag-on-merge.yml` — CalVer tag + `CHANGELOG/` on merge. +- `CHANGELOG/` — per-CalVer history. +- `README.md` — user overview only; never agent guidance. + +## Load these skills first (R0) + +- `/charly-distros:github-runner` — the owning skill: candy properties, packages, + the token contract, the lifecycle hooks, and the org-runner routing playbook. + Load before editing, building, deploying, or troubleshooting this candy. +- `/charly-distros:container-nesting` — the rootless nested podman/buildah/skopeo + stack the candy requires (`layer-container-nesting`). +- `/charly-pod:pod` — the `kind: pod` / deploy schema reference (this candy is + composed into a box; tree-position nesting, volumes, ports). +- `/charly-check:check` — the check/R10 framework: the `check:` step verbs and + `charly check run `. +- `/charly-image:layer` — the candy authoring reference (`charly.yml` schema, + `plan:` step verbs, `env_accept` / `secret_accept`, lifecycle hooks). +- `/charly-build:secrets` — the credential store backing `RUNNER_TOKEN`. +- `/charly-internals:git-workflow` — before any git/PR action. + +## Build / validate / test + +- `charly box validate` at the repo root — the structural check: the manifest + must parse and validate at the installed charly. +- The live R10 witness is a composing box's `check` bed; the candy's own `check:` + steps assert `config.sh` + `run.sh` presence, `config.sh --version` (proving the + `.NET` deps resolved), `skopeo`/`buildah`/`cosign`/`go` versions, the aarch64 + qemu interpreter, rootless nested `podman`, the runner running as uid 1000, and + the `newuidmap` capability. +- The merge gate is the **org-wide** `charly/pr-validator` (required check + `validate / validate`, defined in `opencharly/.github`); this repo has **no** + per-repo candy gate. Its only workflow file is + `.github/workflows/tag-on-merge.yml`. + +## Modify this repo + +- Edit the `github-runner:` candy entity in `charly.yml`; the `skill:` entity in + the same file is the owning skill's source — a candy change and its skill change + land together. +- The runner version pin is the `RUNNER_VERSION` var; the registration logic is + the token-guarded `post_enable` / `pre_remove` hooks. Keep them token-guarded — + an empty `RUNNER_TOKEN` must stay a clean no-op for token-less beds. +- `podman`/`buildah`/`skopeo`/`crun`/`fuse-overlayfs` come from + `layer-container-nesting`; do not redeclare them here (R3). +- The `skill:` entity is the source for `/charly-distros:github-runner`; never + edit the generated `SKILL.md` — regenerate it. + +## Landing + +- PR-only. Every change lands through a pull request; the org-required + `charly/pr-validator` validates the diff and body and arms native auto-merge on + PASS. Direct pushes to `main` are blocked. +- History lives in `CHANGELOG/` (written by `tag-on-merge` at merge time); the PR + body IS the changelog. +- The authoritative rulebook is the umbrella `AGENTS.md` in + `opencharly/opencharly` and `charly/AGENTS.md` in the charly repo. Do not + restate its rules here. diff --git a/README.md b/README.md index 6d0efba..948d07b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,54 @@ # pod-github-runner -The `pod-github-runner` candy of the [opencharly/charly](https://github.com/opencharly/charly) -candy library, as a standalone repo (the candy de-submodule cutover, kind-prefixed -naming). The candy manifest lives at the repo root; the charly resolver fetches -this repo at the pinned tag. +The `github-runner` candy of the OpenCharly candy library, as a standalone repo +(kind-prefixed naming). It ships a GitHub Actions self-hosted runner that builds +CI jobs rootless inside a disposable box. + +## What it provides + +Installs the pinned `actions/runner` release (default `2.334.0`) under +`${HOME}/actions-runner` (`config.sh` + `run.sh`, run as uid 1000) plus the CI +toolchain — `jq`/`git`/`go`/`cosign`, `qemu-user-static` for aarch64 binfmt +cross-builds, and the rootless nested container stack (`podman`/`buildah`/`skopeo` +via `container-nesting`). The `.NET` runtime deps (`icu`/`krb5`/`openssl`/ +`libunwind`/`lttng-ust`) are declared explicitly because the runner's +`installdependencies.sh` has no Arch branch. + +| Property | Value | +|---|---| +| Service | `github-runner` (`~/actions-runner/run.sh`, `restart: always`, uid 1000) | +| Requires | `layer-supervisord`, `layer-container-nesting` | +| Volume | `state` at `~/actions-runner` | +| Env | `RUNNER_WORK_DIR=~/actions-runner/_work`, `RUNNER_GROUP=Default` | +| env_accept | `RUNNER_ORG` — the org/user to register with | +| secret_accept | `RUNNER_TOKEN` — the registration token (credential-store backed) | + +## Registration + +Registration is token-guarded. A deploy with `RUNNER_TOKEN` empty is a clean +no-op (so a check bed brings the image up without registering); with a token, +the `post_enable` hook runs `config.sh --unattended`, and `pre_remove` +deregisters. + +```bash +TOKEN=$(gh api -X POST /orgs/myorg/actions/runners/registration-token --jq .token) +charly config -e RUNNER_ORG=myorg -e RUNNER_TOKEN="$TOKEN" +charly start +``` + +## Layout + +- `charly.yml` — the `github-runner:` candy entity plus its `skill:` entity. +- `.github/workflows/tag-on-merge.yml` — CalVer tag + `CHANGELOG/` on merge. +- `CHANGELOG/` — per-CalVer history. +- `README.md` — this user overview. + +## Related + +- Owning skill: `/charly-distros:github-runner` — the candy properties, the + packages, the token contract, the lifecycle hooks, and the org-runner routing + playbook. +- `/charly-distros:container-nesting` — the rootless nested podman/buildah/skopeo + stack the candy requires. +- [`opencharly/charly`](https://github.com/opencharly/charly) — the charly CLI and image builder +- [`opencharly/opencharly`](https://github.com/opencharly/opencharly) — the umbrella