Cutting Releases

Cutting Releases

Releases are driven by annotated git tags. When a tag matching v* is pushed, .github/workflows/release.yml runs GoReleaser to build binaries, generate a changelog, and create the GitHub release.

Process

Before starting step 1, read pre-flight.md in this skill's directory and complete the pre-flight audit. Do not proceed until the user confirms GO.

Follow these steps in order.

1. Confirm the branch

Releases should be cut from main. Verify you are on main and up to date:

git checkout main && git pull --tags --force

2. Determine the version

Check the latest final tags (the first lines of the output) — RC/alpha/beta tags sort above their final, so exclude anything with a - suffix:

git tag --sort=-v:refname | grep -v -- -

Decide the next target final version following semver. Every release is cut as a release candidate first (step 6) and promoted to this final version only after the RC gate passes and the fleet images are repinned (step 8) — so what you pick here is the version the release will end up as, not the first tag you push:

3. Confirm the version with the user

Use AskUserQuestion to present your proposed version tag and the rationale for your choice. For example:

I'd suggest v0.2.0 (cut first as v0.2.0-rc.1) — there are 5 new feat: commits since v0.1.0 and no breaking changes. Does that look right, or would you prefer a different version?

Do not proceed until the user confirms.

4. Ask for a tag subject

Use AskUserQuestion to ask:

Any special title for this release? (e.g. "MVP Release Candidate 1") Leave blank to use just the version tag.

The answer becomes the tag subject line. If blank, use the tag name itself as the subject so that GoReleaser's name_template guard (ne .TagSubject .Tag) suppresses it, producing a clean release title without duplication.

5. Gather changes since the last final

git log --oneline <previous-final>..HEAD

Summarize changes into categories (features, fixes, refactors). Exclude docs:, test:, chore:, ci:, build: commits — GoReleaser filters these anyway.

6. Create the RC tag

Every release starts as a release candidate. Record the commit you are tagging as <rc-sha> (git rev-parse HEAD).

Build the tag message:

• Line 1 (subject): The custom title from step 4, if one was given. If no custom title, use the tag name itself (e.g. v0.9.0-rc.1) — git's %(contents:subject) skips leading blank lines, so a blank first line still picks up the first category header as .TagSubject. Using the tag name as subject ensures .TagSubject == .Tag, which the goreleaser guard suppresses, producing a clean release title with no suffix.
• Line 2: Blank.
• Lines 3+: Summary of highlights organized by category.

git tag -a vX.Y.Z-rc.N <rc-sha> -m "<message>"
git rev-parse vX.Y.Z-rc.N^{commit}

The second command must print <rc-sha>.

The first line of the annotation becomes the release title suffix via GoReleaser's name_template (see .goreleaser.yml).

7. Push the RC tag

git push origin vX.Y.Z-rc.N
gh run list --workflow=release.yml --branch vX.Y.Z-rc.N --limit=1

Expect about 15 minutes before anything is published: the gate runs agents' release tier, one functional-test case per agent (the full suite takes about 45; see Notes). When it passes, GoReleaser publishes the vX.Y.Z-rc.N binaries as a prerelease. v0 does not move, but tag-agents tags fullsend-ai/agents at vX.Y.Z-rc.N. The images come from the separate Sandbox Images run for the same tag push.

Hold window: from this push until the final tag is pushed, do not merge PRs touching images/sandbox, images/code or .github/workflows/sandbox-images.yml — any such merge forces rc.N+1 at step 9.

If the run fails, see "When a release run fails" in Notes.

8. Repin the fleet harness images

Once the RC run is green, repin the agents harness images to this RC's digests. The final tag waits until this repin PR is merged.

1. Check the image build. The Sandbox Images run for the tag must be green; if it failed, re-run it (gh run rerun <run-id> --failed) and wait before resolving digests:

   gh run list --workflow=sandbox-images.yml --branch vX.Y.Z-rc.N --limit=1

2. Resolve the digests. Needs skopeo; on macOS pass --override-os linux. Image tags have no v prefix:

   skopeo inspect --override-os linux --no-tags docker://ghcr.io/fullsend-ai/fullsend-sandbox:X.Y.Z-rc.N
   skopeo inspect --override-os linux --no-tags docker://ghcr.io/fullsend-ai/fullsend-code:X.Y.Z-rc.N

   Record each result's Digest (the multi-arch index digest) as the sandbox and code RC digests; B3 in post-flight checks against them. Its org.opencontainers.image.revision label must equal <rc-sha>; if not, the tag was rebuilt from another commit — stop and investigate.

3. Hand off the repin PR against fullsend-ai/agents. List the harness files that pin these images on agents main:

   for f in $(gh api "repos/fullsend-ai/agents/contents/harness?ref=main" --jq '.[].name'); do gh api "repos/fullsend-ai/agents/contents/harness/$f?ref=main" --jq ".content|@base64d|split(\"\n\")[]|select(test(\"image:.*fullsend-(sandbox|code)\"))|\"$f: \"+."; done

   Expect one line per harness that pins an image; empty output or an error means discovery failed — stop. This skill can't clone or open PRs in agents, so use AskUserQuestion to give the user the discovered lines and both RC digests, and ask them to open the repin PR with fullsend-ai/agents#1570 as the template: each image: gets the matching index digest (@sha256:...), never a tag or a per-platform digest.

4. Wait for the repin PR to merge, and record its merge commit as <repin-merge-sha> (gh pr view <n> --repo fullsend-ai/agents --json mergeCommit --jq .mergeCommit.oid); post-flight B2 needs it.

9. Tag and push the final release

Tag the final at <final-sha>, normally <rc-sha> itself: the release workflow pins GoReleaser's current tag to the pushed ref, so a final can share the RC's commit. If you move the final to a later commit instead, first check that the images have not changed since the RC:

git log --oneline <rc-sha>..<final-sha> -- images/sandbox images/code .github/workflows/sandbox-images.yml

If it prints anything, do not tag the final: cut rc.N+1 at <final-sha> (step 6) and repin again. Tag with the step 6 message minus -rc.N:

git tag -a vX.Y.Z <final-sha> -m "<message>"
git rev-parse vX.Y.Z^{commit}
git push origin vX.Y.Z

The second command must print <final-sha>. This run is the first gate against the repinned images. On success it publishes the binaries and GitHub Release, moves v0, and tags agents vX.Y.Z. If it fails, see "When a release run fails" in Notes.

10. Run post-flight verification

Read post-flight.md in this skill's directory and follow the post-flight verification procedure.