Every Monday morning .github/workflows/weekly-release.yml tags the newest green commit on main as v<VERSION>, publishes a GitHub Release from the CHANGELOG headlines and fast-forwards refs/heads/stable to it (scripts/release-cut.ts; workflow_dispatch with dry_run, and ref for a hotfix). Team-mode installs follow stable through the new update_channel key (auto: stable when team_mode, else main) in bin/gstack-session-update, bin/gstack-update-check, bin/gstack-upgrade and /gstack-upgrade. Per-merge stamping and the merge train are unchanged. docs/releases.md explains it. Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
6.0 KiB
Releases and update channels
gstack stamps a version at every merge to main, about a dozen a day. Since late October 2026 there is also a weekly tagged release, and team-mode installs follow it instead of every merge.
What a release is
Every Monday at 07:00 Pacific (06:00 in winter) the Weekly release
workflow (.github/workflows/weekly-release.yml, which runs
scripts/release-cut.ts) takes the newest green commit on main and:
- tags it
v<VERSION>(the VERSION file at that commit, an annotated tag); - publishes a GitHub Release whose notes are one line per CHANGELOG version since the previous release, with a compare link and a link to the full CHANGELOG at that tag;
- fast-forwards the
stablebranch to it.
A tag and its release never change. stable is a moving pointer: always a
commit on main's first-parent history, moved only by this workflow, only
forward.
Green means, on that exact commit: the free-tests check run succeeded
(the status main requires), no completed check run failed, the Main backstop
gate run for that push completed with conclusion success (a green train record
covers the tree, or the backstop gated it green), and refs/notes/gstack-trains
holds no active freeze. A commit whose gate is still running is skipped and the
next older one is considered, back through 7 days or 200 first-parent commits.
The workflow runs no tests and no paid evals of its own; it only reads what the
trains and the backstop already recorded. With nothing green in the window it
fails and lists why each commit was skipped.
Channels
| Channel | Follows | Who |
|---|---|---|
stable |
refs/heads/stable: the weekly release, plus any hotfix cut off-cycle |
team mode (./setup --team) by default |
main |
every merge to main | plain ./setup, contributors, Capy crew machines |
The config key is update_channel (bin/gstack-config):
gstack-config get update_channel # auto (default) | stable | main
gstack-config set update_channel main # a team install that wants every merge
gstack-config set update_channel stable # a solo install that wants weekly releases
gstack-config unset update_channel # back to auto
auto resolves to stable when team_mode is true and to main otherwise,
so existing team installs moved to weekly releases with nothing to migrate and
contributor installs did not move at all. GSTACK_UPDATE_CHANNEL=stable|main
overrides the key for one command. The resolution lives in one helper,
bin/gstack-update-channel.sh, used by:
bin/gstack-session-update, the team-mode session-start hook: it fetches the channel ref and fast-forwards to it. Its log (<state root>/analytics/session-update.log) carriesCHANNEL stable target=<sha>when it follows a release.bin/gstack-update-check, the "update available" line in every skill preamble: it reads<channel>/VERSIONand compares withrefs/heads/<channel>, so a stable install is not told every hour that main moved.bin/gstack-upgradeand/gstack-upgrade: they fast-forward to the channel ref (UPSTREAM_REF=origin/stablein the skill's output) and say which channel they followed.
Two edge cases are handled on purpose:
- Before the first release exists origin has no
stable. Every caller then follows main and says so (CHANNEL_FALLBACK stable->mainin the hook log,channel stable has no release on origin yetfromgstack-upgrade). - An install already past the release (it followed main until now, or a hotfix was cut below it) stays where it is until stable passes it. The updater never moves a checkout backwards. A depth-1 clone cannot see that an older release is its ancestor, so the VERSIONs decide: main stamps a higher version at every merge and stable is always a main commit.
The local branch stays main either way. A stable install is a main
checkout parked at the last released commit, which is why fast-forward-only
still holds and nothing about version stamping changed.
Cutting a release by hand (hotfixes)
A hotfix is an ordinary PR: it merges to main through a train and gets its version like any other change. To put it on stable before Monday, run the workflow by hand with the merge commit's SHA:
gh workflow run weekly-release.yml -f ref=<full sha on main> -f dry_run=false
or Actions → Weekly release → Run workflow. The same green checks apply. The commit is tagged with its VERSION, the release notes say "hotfix release" and list every version since the previous release (everything merged in between ships with it), and stable fast-forwards. Team installs pick it up at their next hourly check.
There is no release branch and no cherry-picking: stable only ever names main commits. If main carries a change that must not ship yet, revert it on main first, then promote.
Dry runs
Run the workflow with dry_run=true (the default for a manual run) to see the
plan without changing anything: the candidate, its VERSION and tag, the stable
move, how many version lines the notes would carry, every skipped commit with
its reason, and the exact commands a real cut would run. The scheduled Monday
run is never a dry run.
gh workflow run weekly-release.yml -f dry_run=true
gh run watch
The step summary carries the same plan plus the full release notes.
Outcomes
| Line | Meaning |
|---|---|
CANDIDATE: <sha> (<date>) |
the commit that will be (or was) released |
NOTHING_NEW: origin/main <sha> is already stable |
nothing merged since the last release; exit 0 |
NO_GREEN_COMMIT: ... with SKIPPED: lines |
nothing in the window passed the gate; exit 1 |
REFUSED: non-fast-forward: ... |
the candidate is behind stable; stable only moves forward |
REFUSED: queue frozen since train ... |
the main backstop froze the queue; clear it first (docs/ship-policy.md) |
REFUSED: tag v<X> already names <other sha> |
a version was stamped twice; needs a look before anything is cut |
TAG:, STABLE:, RELEASE: |
what the cut did; a re-run reports each step as already done |