From 6ef82934dc3e6067293743e44f37e72fc33cca11 Mon Sep 17 00:00:00 2001 From: Erik Date: Wed, 19 Aug 2026 13:44:55 +0200 Subject: [PATCH] docs: SSOT for the Gitea CI pipeline and automated alpha releases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/ci-and-releases.md documents what happens on a push to main, why Gitea rather than GitHub (billing-blocked, private repo, and Forgejo ships no hosted runners), both runners and their prerequisites, the release/manifest layout, and how to verify a release with the Lane=Live install test. Its landmine table is the part worth keeping: every row cost a red pipeline — Node for JS actions, setup-dotnet unmirrored on data.forgejo.org, the zombie-task timeout caused by run-release-gate.ps1 redirecting child output, an en-SE runner locale breaking 40 tests on decimal commas, DAT tests missing their InstalledDat lane tag, parallel-load timing flakes, and the Avalonia compositor threading failure that must NOT be 'fixed' by de-async-ing the test. Also records the culture finding: config, parsing and the wire are all invariant-safe, so US and European installs behave identically; only diagnostic strings follow the current culture. Cross-linked from docs/README.md and release-gate.md, which keeps ownership of the local bounded gate. --- docs/README.md | 2 + docs/ci-and-releases.md | 117 ++++++++++++++++++++++++++++++++++++++++ docs/release-gate.md | 8 +++ 3 files changed, 127 insertions(+) create mode 100644 docs/ci-and-releases.md diff --git a/docs/README.md b/docs/README.md index 328d201e..9b1ceb78 100644 --- a/docs/README.md +++ b/docs/README.md @@ -82,6 +82,8 @@ document in the same change; do not leave both claims standing. - [`superpowers/specs/`](superpowers/specs/) and [`superpowers/plans/`](superpowers/plans/) are per-slice design and execution records. Completed plans remain historical. +- [`ci-and-releases.md`](ci-and-releases.md) is the SSOT for the Gitea CI + pipeline, the self-hosted runners, and how alpha releases are published. - [`audit/`](audit/) contains completion and conformance audits. - [`reference/ace-commands.md`](reference/ace-commands.md) preserves the local ACE server's complete in-game command catalog and points to the authoritative diff --git a/docs/ci-and-releases.md b/docs/ci-and-releases.md new file mode 100644 index 00000000..ecedc638 --- /dev/null +++ b/docs/ci-and-releases.md @@ -0,0 +1,117 @@ +# Continuous integration and alpha releases (Gitea) + +Single source of truth for how acdream builds, gates, and ships alpha builds. +Landed 2026-08-19. Companion to [`release-gate.md`](release-gate.md), which +owns the *local* bounded gate. + +## What happens on a push to main + +``` +git push origin main + │ + ├─ windows-gate (RARE-win) build + full lane-filtered suite + ├─ linux-portable (eriktestLinux) portable closure, Linux lanes + │ + └─ release (needs BOTH green) publish a Gitea Release + + repoint the launcher manifest +``` + +Workflow: [`.gitea/workflows/ci.yml`](../.gitea/workflows/ci.yml). A red gate +cannot publish: `release` uses `needs:`, not a `workflow_run` trigger, whose +Forgejo support is unreliable. + +## Why Gitea and not GitHub + +GitHub Actions is **billing-blocked** on this account ("recent account payments +have failed"), and the repo is private, so hosted runners consume paid minutes. +Forgejo ships **no hosted runners at all**, so Actions there requires +self-hosted ones — which are free on both platforms. The same two machines can +serve GitHub later by registering a second agent; only the workflow's +`runs-on` labels change. + +## The runners + +| | Windows | Linux | +|---|---|---| +| Host | `RARE` (10.6.0.3) | `eriktestLinux` (10.0.0.202) | +| Agent | `act_runner` 0.2.13 | `forgejo-runner` 13.0.0 | +| Persistence | Scheduled task `ForgejoRunner`, at logon of `acbot` | systemd `forgejo-runner`, `Restart=always` | +| Labels | `windows`, `windows-latest`, `windows-x64` | `ubuntu-latest`, `ubuntu`, `linux`, `ubuntu-slim` | +| Execution | host mode (`:host`) — no Docker on either box | host mode | + +Both **poll outbound** over HTTPS. Gitea never connects to them, so no inbound +ports, no port forwarding, and no static IP; they work behind NAT. The runner +does not have to live next to the Gitea container (which runs on `bluesnake`, +a host we have no shell on). + +`forgejo-runner` publishes **no Windows binary in any release**, which is why +Windows uses Gitea's `act_runner`. Forgejo speaks the same Actions protocol. + +### Prerequisites on a runner + +- **.NET SDK in the `global.json` band** — currently `10.0.3xx`. `10.0.400` is a + different feature band and `rollForward: latestPatch` rejects it. +- **Node.js** — `actions/checkout` and `actions/upload-artifact` are JavaScript + actions. Docker images normally supply Node; in host mode the machine must. +- **Git**, and outbound HTTPS to `git.snakedesert.se`. +- **PowerShell 7** on Windows (`pwsh`); `tools/*.ps1` require it. + +## Releases + +Payloads are **release attachments**, deliberately outside git history: a build +is ~120 MB and would otherwise land in a branch every push. Only the ~500-byte +`manifest.json` is committed, to the payload-free `dist` branch. + +``` +Release 0.1.0-build. + client-win-x64.zip AcDream.App.exe + acdream-headless.exe + launcher-win-x64.zip acdream-launcher.exe + acdream-bake.exe + manifest.json + +dist branch (manifest only, force-replaced each publish) + bin/manifest.json -> points at the release attachment URLs +``` + +The launcher polls the manifest at a fixed raw URL +(`ReleaseManifestClient.ProductionManifestUri`). **Forgejo has no +`/releases/latest/download/` route** (verified: 404), which is why the manifest +cannot simply live in the release itself. + +`tools/publish-bin.ps1 -BaseUrl ` builds the payloads; the +pipeline passes the tag's asset base. With no `-BaseUrl` it falls back to the +dist-branch layout for a manual local publish. + +### Verifying a release + +```powershell +dotnet test tests/AcDream.Launcher.Core.Tests --filter Lane=Live +``` + +`LiveGiteaReleaseInstallTests` installs the advertised client from the real feed +through the production updater — real SHA-256/size verification, extraction, and +atomic activation — then asserts both hosts resolve out of the activated +directory and `current.json` names the installed version. + +## Landmines + +Each of these cost a red pipeline; none was a config typo. + +| Symptom | Cause | +|---|---| +| `Cannot find: node in PATH` | JS actions need Node on the host in `:host` mode | +| `actions/setup-dotnet` never resolves | `data.forgejo.org` does not mirror it (404). `checkout` and `upload-artifact` **are** mirrored. Self-hosted runners carry the SDK anyway | +| Job "failed" while dotnet processes still run | `run-release-gate.ps1` redirects children to log files, so the step goes silent; Forgejo fails a non-reporting task as a zombie. CI runs `dotnet test` directly so output streams | +| ~40 tests fail on formatted numbers | Runner's `HKCU` locale was `en-SE` (comma decimal): expected `"update:0.25"`, got `"update:0,25"`. `Set-Culture` does **not** reach a scheduled task without a loaded profile — set the registry directly | +| `DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1` as the locale fix | Too blunt — it breaks tests that legitimately construct a culture. Fix the machine locale instead | +| `FileNotFoundException: client_cell_1.dat` | DAT-dependent tests missing `[Trait("Lane", "InstalledDat")]`. Build machines have no DATs | +| Timing-sensitive test fails only under load | `FakeAceTransportTests.PausedSelector_…` took 37 s under full-assembly parallelism vs ~350 ms isolated. Cap `xUnit.MaxParallelThreads` on small runners rather than edit transport code | +| Avalonia "calling thread cannot access this object" in cleanup | Serialize that assembly (`xunit.runner.json`). The stack shows a compositor being **constructed** during teardown; `TestAppBuilder` documents the hazard. Do **not** "fix" it by de-async-ing the test — that causes the failure | + +## Culture note + +The `en-SE` discovery is worth remembering beyond CI: config files, numeric +parsing, and the wire are all culture-safe (`System.Text.Json` is invariant by +spec, every `float/double.TryParse` passes `CultureInfo.InvariantCulture`, and +the protocol is binary). Only **diagnostic strings** format with the current +culture, so a European player sees `local=(8,00; 191,00)` in an F3 dump. The +client installs and runs correctly in both the US and Europe. diff --git a/docs/release-gate.md b/docs/release-gate.md index a75421e6..f6d968ba 100644 --- a/docs/release-gate.md +++ b/docs/release-gate.md @@ -72,6 +72,14 @@ The JSON summary records the exact test filter. Environment-dependent, diagnostic, manual, and known-failure results must be published as their own lane and must never be added to the hermetic pass headline. +## Continuous integration + +This document owns the LOCAL gate. Pushes to `main` are gated on self-hosted +runners and publish alpha releases — see +[`ci-and-releases.md`](ci-and-releases.md). Note that CI deliberately does NOT +invoke `run-release-gate.ps1`: that script redirects child output to log files, +and Forgejo fails a task that stops reporting as a zombie. + ## Non-hermetic test lanes Installed-DAT tests require an explicit opt-in and a retail DAT directory: