From 78ae47bf11bbeaeb2a40337b6501e9e63c807013 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 17 Nov 2026 09:24:30 -0500 Subject: [PATCH] G8: bump ericomeehan.gitea for the Actions cache; document it Picks up DevOps/ansible-role-gitea@96e5b92, which turns on the runner's built-in cache server with a persistent volume. runner.md describes the cache and how to troubleshoot or clear it, and corrects the DinD CPU limit to the 750m now set for the current runner node. adding-ci.md shows how a workflow uses actions/cache, pinned by SHA. Refs #56 Co-Authored-By: Claude Opus 5.5 --- docs/ci-cd/adding-ci.md | 26 ++++++++++++++++++++++++++ docs/ci-cd/runner.md | 36 ++++++++++++++++++++++++++++++++++-- roles/ericomeehan.gitea | 2 +- 3 files changed, 61 insertions(+), 3 deletions(-) diff --git a/docs/ci-cd/adding-ci.md b/docs/ci-cd/adding-ci.md index aba9e76..aca2909 100644 --- a/docs/ci-cd/adding-ci.md +++ b/docs/ci-cd/adding-ci.md @@ -174,6 +174,32 @@ jobs: | `dockerfiles` | every `Dockerfile*` and `*.Dockerfile` | Space-separated paths. The job fails if it finds none. | | `failure-threshold` | `warning` | `error`, `warning`, `info` or `style`. Use a `.hadolint.yaml` for per-rule ignores. | +## Caching dependencies (G8) + +The runner serves the Actions cache, so `actions/cache` works as on GitHub. +Use it for downloads that are slow and change rarely (npm, pip, Go modules, +Ansible collections). Don't cache build outputs that are cheap to rebuild. + +```yaml + - name: restore npm cache + uses: actions/cache@caa296126883cff596d87d8935842f9db880ef25 # v5.1.0 + with: + path: ~/.npm + key: npm-${{ hashFiles('package-lock.json') }} + restore-keys: npm- +``` + +- Pin by SHA, like every other action here (see + [actions-inventory.md](actions-inventory.md)). v4.3.0 + (`0057852bfaa89a56745cba8c7296529d2fc39830`) also works. +- Put a hash of the lock file in the key, so a dependency change makes a new + entry instead of restoring a stale one. +- Entries are per repository. Unused entries expire after 7 days, and every + entry after 30. The first run on a new key is always a miss. +- Never cache anything that holds a secret. Anyone who can run a workflow in + the repo can restore its cache. +- If the cache is down, the step warns and the job carries on without it. + ## How these were tested (2026-11-14) Each workflow's `run:` steps were taken from the YAML as written and run inside diff --git a/docs/ci-cd/runner.md b/docs/ci-cd/runner.md index 3dbd4a8..22caca7 100644 --- a/docs/ci-cd/runner.md +++ b/docs/ci-cd/runner.md @@ -18,7 +18,8 @@ gitea (Deployment, ns gitea) <── polls for jobs ── gitea-actions-runner- ├─ init: reach-gitea waits until Gitea answers ├─ dind Docker daemon; job containers run here ├─ docker-prune (sidecar) cleans Docker data every 15 min (S5) - └─ runner act_runner; talks to dind over a socket + └─ runner act_runner; talks to dind over a socket; + serves the Actions cache on port 8088 (G8) ``` - **One runner for everyone.** It is registered at instance level, so every @@ -39,11 +40,21 @@ gitea (Deployment, ns gitea) <── polls for jobs ── gitea-actions-runner- - **Registration token.** Kubernetes Secret `gitea-actions-runner-token` in namespace `gitea`. The role creates it once with `gitea actions generate-runner-token` and never prints it. +- **Actions cache** (G8, #56). The runner's built-in cache server backs + `actions/cache`. Its files are on a separate PVC, `gitea-actions-cache` + (`gitea_actions_cache_size`, 20Gi), mounted at `/cache` in the `runner` + container, so cached dependencies survive a runner restart even though + DinD's Docker data doesn't. Job containers reach the server at the pod's own + IP on port 8088 (`gitea_actions_cache_port`). Each job gets its own token, + and entries are scoped per repository. The runner removes entries unused for + 7 days, and any entry older than 30 days. The storage is NFS, which doesn't + enforce the PVC size, so that expiry is what keeps it bounded. - **Job images.** `ubuntu-latest`, `ubuntu-24.04` and `ubuntu-22.04` map to dated `docker.gitea.com/runner-images` tags (`gitea_actions_runner_labels`). `force_pull` is off, so they stay cached in DinD and the cleanup never removes them. -- **Limits.** DinD gets up to 2 CPU and 8Gi memory, and holds every job +- **Limits.** DinD gets up to 750m CPU (sized for the current 1-CPU runner + node; go back to 2 on a dedicated node) and 8Gi memory, and holds every job container. A job over the memory limit is OOM-killed and fails with a step error. The runner fails a job after 2h; Gitea fails one after 2h30m (`ENDLESS_TASK_TIMEOUT`), marks one whose runner stops reporting as failed @@ -161,6 +172,27 @@ device`. until Gitea's task timeout fails it; cancel it first. See [soak-test.md](soak-test.md) for what this looks like in a job's log. +### Cache misses, or cache errors in jobs + +Signs: `actions/cache` warns `Failed to restore` or `Failed to save`, or +always reports a miss for a key that a previous run saved. + +1. Check the runner log for `artifactcache` lines: + `kubectl -n gitea logs gitea-actions-runner-0 -c runner | grep -i cache`. +2. Check the volume is mounted and has space: + `kubectl -n gitea exec gitea-actions-runner-0 -c runner -- df -h /cache`. +3. A miss is normal for the first run on a new key, and after the entry has + expired (see Architecture). Keys are per repository, so one repo never + restores another's cache. +4. To clear the whole cache, while no job is running, remove the files and + restart the pod so the runner starts a fresh index: + `kubectl -n gitea exec gitea-actions-runner-0 -c runner -- sh -c 'rm -rf /cache/*'`, + then `kubectl -n gitea delete pod gitea-actions-runner-0`. Jobs only lose + speed, never data. +5. To switch the cache off, set `gitea_actions_cache_enabled: false` and apply + with `--tags actions`. Workflows that use `actions/cache` still pass; the + step just warns and skips. + ### kubectl itself fails If `kubectl` errors with a TLS or certificate message, the problem is the diff --git a/roles/ericomeehan.gitea b/roles/ericomeehan.gitea index 3974f60..96e5b92 160000 --- a/roles/ericomeehan.gitea +++ b/roles/ericomeehan.gitea @@ -1 +1 @@ -Subproject commit 3974f603fc65cbb92844485ef0fffe367c14ce26 +Subproject commit 96e5b92becb99667532b7749d840e30f94408ae5