From 63cccdc958622e3eba4dab79b433df469e72829b Mon Sep 17 00:00:00 2001 From: Ilia Denisov Date: Thu, 7 May 2026 08:49:43 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20testing.md=20=E2=80=94=20local=20gitea?= =?UTF-8?q?=20ci=20cheat=20sheet?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replaces the act-as-fallback section with the operations needed to work with the local Gitea + arm64 act_runner shipped in tools/local-ci/: how to bring it up, push, query run status from curl, and pull zstd-compressed step logs from inside the gitea container. Keeps a short act note as a syntax-only dry-run. Also drops `client/**` from the path-filter list documented at the top (the workflow excludes deprecated client/ from triggers and from the go test command), and notes that the checkout step now uses submodules: recursive so MaxMind-DB fixtures land for pkg/geoip. Co-Authored-By: Claude Opus 4.7 --- ui/docs/testing.md | 96 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 89 insertions(+), 7 deletions(-) diff --git a/ui/docs/testing.md b/ui/docs/testing.md index 5e83635..ab34d4c 100644 --- a/ui/docs/testing.md +++ b/ui/docs/testing.md @@ -9,7 +9,11 @@ this doc only covers the UI-specific tiers added in Phase 2 of Triggered by `.gitea/workflows/ui-test.yaml` on every push and pull request that touches `ui/**`, `backend/**`, `gateway/**`, `game/**`, -`pkg/**`, `client/**`, `go.work`, or `go.work.sum`. Linux runner only. +`pkg/**`, `go.work`, or `go.work.sum`. Linux runner only. + +The `actions/checkout@v4` step uses `submodules: recursive`, so the +runner pulls every git submodule the suite depends on (today only +`pkg/geoip/test-data`, the MaxMind-DB fixtures used by `pkg/geoip`). Runs: @@ -79,14 +83,92 @@ go test -count=1 \ ./pkg/storage/... ./pkg/transcoder/... ./pkg/util/... ``` -## CI dry-run with `act` +## Local CI verification -Until the Gitea Actions runner is wired up, the workflow is exercised -locally with [`act`](https://github.com/nektos/act): +`tools/local-ci/` ships a self-contained Gitea + Actions runner via +docker-compose so workflow changes are exercised end-to-end on a real +runner before pushing to a remote Gitea instance. On Apple Silicon +the runner and every spawned workflow container are arm64-native +(no QEMU). Full runbook lives in +[`../../tools/local-ci/README.md`](../../tools/local-ci/README.md); +the cheat sheet below covers the operations needed when working a +phase that touches CI. + +### Bring up / push / tear down ```sh -act -W .gitea/workflows/ui-test.yaml --container-architecture linux/amd64 +make -C tools/local-ci up # idempotent: gitea + runner + admin user + repo +make -C tools/local-ci push # add `local-gitea` remote (first call) and push HEAD +make -C tools/local-ci status # docker compose ps +make -C tools/local-ci logs # tail container logs +make -C tools/local-ci down # stop, keep state +make -C tools/local-ci clean # stop and wipe volumes for a fresh start ``` -`act` reads the workflow as GitHub Actions; the format is -intentionally compatible. +Default credentials baked in: `galaxy:galaxy-dev` (admin user, also +the owner of the `galaxy/galaxy` repo). Web UI on +; runs at +. + +### Inspect a run from the shell + +The Gitea Actions API is on `http://localhost:3000/api/v1` with basic +auth. Useful for verifying a workflow change without opening the +browser: + +```sh +# Latest workflow runs — `status` is a human-readable string here: +# "running" / "success" / "failure" / "cancelled". +curl -s -u galaxy:galaxy-dev \ + 'http://localhost:3000/api/v1/repos/galaxy/galaxy/actions/tasks?limit=5' \ + | python3 -m json.tool + +# Tight one-liner for the latest run only: +curl -s -u galaxy:galaxy-dev \ + 'http://localhost:3000/api/v1/repos/galaxy/galaxy/actions/tasks?limit=1' \ + | python3 -c 'import json, sys; r=json.load(sys.stdin)["workflow_runs"][0]; print(r["run_number"], r["status"], r["display_title"])' +``` + +Step-by-step workflow output is stored zstd-compressed under +`/data/gitea/actions_log/galaxy/galaxy//.log.zst` +inside the gitea container: + +```sh +docker compose -f tools/local-ci/docker-compose.yml exec -T gitea sh -c ' + apk add --quiet zstd + zstdcat /data/gitea/actions_log/galaxy/galaxy/01/1.log.zst +' | less +``` + +`` is the run number, zero-padded to two digits +(`01`, `02`, …); `` is the 1-based index of the job +inside that run (only `1` for the current single-job workflows). + +### Typical phase workflow + +When a phase changes anything under `.gitea/workflows/` or surfaces +new tests in CI: + +1. Local sanity first — run the affected commands directly + (`pnpm test`, `pnpm exec playwright test`, the targeted + `go test ./...` slice). +2. Commit and `make -C tools/local-ci push`. +3. Poll the API for the latest run; once it leaves `running`, + inspect status. On failure pull the log via the snippet above. +4. Fix and repeat. The runner is always-on; each push triggers a + fresh run (test cache is cleared by `-count=1` so a green run is + honest). + +### Quick syntax-only dry-run with `act` + +For a sub-second check that the workflow YAML is well-formed and +action references resolve, without pulling images and without +running anything: + +```sh +act -W .gitea/workflows/ui-test.yaml -n push +``` + +`act` doesn't honour Gitea-specific behaviours (artifact storage, +secrets, run triggers). Use it for syntax checks; fall back to the +local Gitea above for honest end-to-end verification.