From 786e1d2e53a095b48bedfc23626dc28a1b76ab89 Mon Sep 17 00:00:00 2001 From: Andreas Niemann Date: Wed, 1 Jul 2026 01:50:59 +0200 Subject: [PATCH] docs(session): correct ecosystem-CI architecture to reusable workflows MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The composite-action pivot was based on a false negative — reusable workflows DO work on Forgejo 11 (caller needs `runs-on`; short cross-repo ref). Correct the SESSION_002 + HANDOVER ecosystem-CI sections, the next-steps Forgejo-upgrade note, and point the required-reads at .forgejo/workflows/README.md. Co-Authored-By: Claude Opus 4.8 (1M context) --- documentation/sessions/HANDOVER.md | 12 ++++--- .../sessions/SESSION_2026-07-01_002.md | 33 ++++++++++--------- 2 files changed, 24 insertions(+), 21 deletions(-) diff --git a/documentation/sessions/HANDOVER.md b/documentation/sessions/HANDOVER.md index 0aaca37..7109246 100644 --- a/documentation/sessions/HANDOVER.md +++ b/documentation/sessions/HANDOVER.md @@ -12,7 +12,7 @@ Continue the **olsitec-foundation** build. You are the **Lead Agent, HIGH-RISK / 2. `documentation/sessions/SESSION_2026-07-01_001.md` ← the prior session (gaps closed, T11/T13/T14-core) 3. `documentation/contracts/CONTRACT_001–004` + `decisions/ADR_004,005,006,007` (**ADR-007** is the control-plane mechanism the whole egg runs on — read it first) -4. `actions/README.md` ← the ecosystem-CI composite-action contract + the Forgejo-11 finding +4. `.forgejo/workflows/README.md` ← the ecosystem-CI reusable-workflow contract + the Forgejo-11 caller quirk 5. `documentation/999_testing.md` ← the operator's acceptance-test plan (now implemented) ## Where things stand @@ -27,9 +27,11 @@ Working tree clean on `master`. `backup-verify.yml` (weekly + dispatch; RESTORE VERIFY PASS from offsite). - `ecosystem-selftest.yml` — semantic-release bump sequence (1.0.0→1.1.0→1.1.1→2.0.0→3.0.0) + eslint/yamllint non-zero-exit gates. -- `actions/` composite actions (node-build, docker-build, lint, semantic-release-version) — the - ecosystem-CI reuse layer. **Forgejo 11 has NO reusable workflows**; downstream repos call composite - actions by FULL URL: `uses: https://forge.olsitec.net/olsitec/foundation/actions/@master`. +- `.forgejo/workflows/reusable-*.yml` (node-build, docker-build, lint, semantic-release) — the + ecosystem-CI reuse layer. Downstream repos call them as + `uses: olsitec/foundation/.forgejo/workflows/.yml@master`. **Forgejo-11 quirk:** the calling job + MUST set `runs-on` (omitting it → silently zero runs; removed by a v15 upgrade) and use the SHORT + cross-repo ref (not a full URL). See `.forgejo/workflows/README.md`. `cd bootstrap && ./run.sh up` is idempotent and now also publishes `pulumi stack export` to RustFS (`bootstrap/state-publish.sh`) so the state-dependent CI has Pulumi state. @@ -69,6 +71,6 @@ Working tree clean on `master`. `docs/DAY-ZERO-TIMELINE.md`. 4. **Hardening** — pin floating refs (`IMAGE_REGISTRY` PIN_DIGEST, `IMAGE_RUSTFS` `latest`, `IMAGE_CI` tag); pre-bake pulumi plugins into `foundation-ci` (drop preview's per-run auto-install); register in Olsitec - MCP (D6); consider a Forgejo upgrade to regain reusable workflows. + MCP (D6); a Forgejo v15 upgrade would drop the reusable-workflow caller `runs-on`/short-ref quirks. Validate each task live (VM `./run.sh up` + the runner for CI) and commit per task. diff --git a/documentation/sessions/SESSION_2026-07-01_002.md b/documentation/sessions/SESSION_2026-07-01_002.md index 412f218..f1e46a2 100644 --- a/documentation/sessions/SESSION_2026-07-01_002.md +++ b/documentation/sessions/SESSION_2026-07-01_002.md @@ -45,24 +45,23 @@ real hardening for when UNTRUSTED workflows run. semantic-release@24.2.3 with the **conventionalcommits preset** + `@semantic-release/ git`+`changelog` (the plugin set Olsitec's GitLab release template uses). Pinned in VERSIONS (NOT in preflight's up-gating set — job tools, not deploy tools). -- **ARCHITECTURE PIVOT — Forgejo 11.0.15 does NOT support reusable workflows.** A - job-level `uses:`/`workflow_call` is silently dropped → **zero runs** (verified live, - both same-repo and cross-repo; an equivalent inline job ran green). The working - cross-repo reuse primitive is the **COMPOSITE ACTION referenced by FULL URL**: - `uses: https://forge.olsitec.net/olsitec/foundation/actions/@master` (short-form - resolves against the runner's `DEFAULT_ACTIONS_URL`=data.forgejo.org and 404s). - Replaced the (dead) `reusable-*.yml` with composite actions. -- **`actions/`** (composite, + README): `node-build` (npm/bun/none install+build), - `docker-build` (host-socket build; caller mounts the socket), `lint` (eslint+yamllint - gate), `semantic-release-version` (conventionalcommits dry-run version probe). +- **Reuse architecture: reusable workflows (`on: workflow_call`).** `.forgejo/workflows/ + reusable-{node-build,docker-build,lint,semantic-release}.yml`, called as + `uses: olsitec/foundation/.forgejo/workflows/.yml@master`. **Forgejo-11 quirk + (verified live):** the pre-v15 "limited" reusable-workflow impl REQUIRES `runs-on` on + the *calling* job — omit it (standard GitHub syntax) and Forgejo silently schedules + **zero runs** (this was an initial false-negative that briefly sent me to composite + actions; reverted). Cross-repo refs use the **short** form (full URL fails — that is + the composite-*action* form). A future Forgejo **v15** upgrade removes both quirks + (omit `runs-on` → workflow expansion). Documented in `.forgejo/workflows/README.md`. - **`.forgejo/workflows/ecosystem-selftest.yml`** + `ci/semantic-release-bumptest.sh`: self-contained proof on the runner of the 999 criteria that need no external repo — the **semantic-release bump sequence** `1.0.0→1.1.0→1.1.1→2.0.0→3.0.0` (Olsitec's exact releaseRules; `--dry-run --no-ci --tag-format '${version}'` + grep, like the GitLab `generate-release-version` job) and the **eslint/yamllint non-zero-exit gates**. **All GREEN.** -- **Candidate validation:** `node-build` ran **green on the runner** against a real bun - build (throwaway `citest-node`, since deleted). Real candidate code built in the - foundation-ci image: **C2 olsicrypto** (npm/tsc → dist) and **C3 document-engine** +- **Candidate validation:** `reusable-node-build` ran **green on the runner** (short + cross-repo ref + `runs-on`) against a real bun build (throwaway `citest-node`, since + deleted). Real candidate code built in the foundation-ci image: **C2 olsicrypto** (npm/tsc → dist) and **C3 document-engine** (bun/tsc → dist). **C4 olsitrack/api** is no-build (install-only path). **C1 seaspots-homepage** and **C5 token-service** are blocked on the not-yet-published `@olsitec` package registry (svelte-common / olsicrypto) — Stage-2; documented. @@ -71,7 +70,8 @@ real hardening for when UNTRUSTED workflows run. - Repo `~/work/olsitec-foundation/foundation`, branch `master`, origin = Forgejo, working tree clean. Commits this session (pushed): `fix(ci-image): pulumi 3.243`, `feat(ci): T14 pipelines`, `feat(ci-image): ecosystem toolchain`, `feat(ci): reusable - workflows + selftest`, `refactor(ci): composite actions (Forgejo 11)` (+ a probe commit). + workflows + selftest`, `refactor(ci): composite actions` → `revert(ci): reusable + workflows after all` (the composite pivot was a false-negative, reverted; + a probe commit). - Foundation's own CI green on master (preflight, typecheck, preview, semantic-release- bumptest, eslint-gate, yamllint-gate). `pulumi-preview` + `backup-verify` green. - `cd bootstrap && ./run.sh up` idempotent; it now also publishes state to RustFS. @@ -85,8 +85,9 @@ real hardening for when UNTRUSTED workflows run. Forgejo package registry populated (publish `olsicrypto`, `svelte-common`, …). Then `docker-build` for seaspots-homepage / token-service can be validated end-to-end (npmrc via `build-args`). -- **Forgejo upgrade** — reusable workflows need a newer Forgejo; until then composite - actions are the contract (`actions/README.md`). +- **Forgejo upgrade (v15)** — reusable workflows already work on v11 with the caller + `runs-on` + short-ref quirks; a v15 upgrade (LTS, Apr 2026) removes both (omit `runs-on` + → workflow expansion + separate logs). See `.forgejo/workflows/README.md`. - **T15** — `index.ts` phase marker still `T10-runner`; Gate A/B comments; `docs/DAY-ZERO-TIMELINE.md`. - **Hardening** — pin floating refs (`IMAGE_REGISTRY` PIN_DIGEST, `IMAGE_RUSTFS` latest,