[aledbf]

Plan steps R5, R6 and R7: the site pins what it is generated from, Gate checks the reference against those pins, and a daily job opens one sync pull request.

R5: pins

• versions.yaml (go-tools versions format, held by versions/gate in tools/sources/repo_test.go) pins:
  • spin at main's 77380b13d. This is the commit the reference already documents. No release has been cut since v20261019.02, and that release has no board.
  • spin-terraform-aws at v20261024.01.
  • brand at its main.
• The files refgen writes that record commits are in the gate's Elsewhere.
• refgen fails when reference.json's commits are not the pins (tools/refgen/pins.go).
• task sources (tools/sources) fetches exactly the pinned commits, with history and tags, into .sources/. SPIN, TERRAFORM and BRAND now default to those directories. It is tested against a local bare repository.
• reference:public uses tools/sources in place of the source task.
• task sources:bump moves the pins:
  • spin moves to a release only when that release holds the pinned commit (GitHub's compare);
  • a release never moves back to an older one;
  • brand follows its main.
• check:public is the path with no credentials.

R6: Gate

• Gate mints a read-only sources-App token for spin alone, then runs task sources and task check.
• With no secret (a fork's pull request), Gate runs task check:public instead.
• tools/sources hands the token to its own git commands as GIT_CONFIG_* (http.extraheader). It is only in the Sources step's environment and is written nowhere.
• setup-go's cache is keyed on versions.yaml as well, so spin's modules and CLI build stay cached until the spin pin moves.

R7: sync

• sync.yml runs daily and on a sources-released repository_dispatch. It bumps the pins, regenerates with no token, and force-pushes sync/sources as the sync App. It opens or updates one pull request and does not auto-merge.
• That pull request lists only the pin moves and the changed files.
• The commit digest goes in one issue in spin, "Site vs spin main", written with the sources App:
  • commits grouped by the spin path that feeds each page, with the pages listed;
  • the release-chain report;
  • a weekly section on how far spin main is past the pin. It is advisory.
• tools/sync builds all of it and is tested with httptest.
• refgen now lists spin's tasks with go tool task in spin's checkout. Gate has no task on PATH, so this uses the Task version spin's own go.mod pins.

Gate time

• Before: 57–92 s.
• On this branch, cold cache: 3 min 26 s. Most of that was compiling with an empty build cache.
• On this branch, warm cache (re-run): 98 s in total.
  • Sources: 11 s (spin fetched with the token).
  • task check: 27 s.
  • Restoring setup-go's cache: 28 s.

🤖 Generated with Claude Code