From abe2bf99fc73ea3830be8bfc2e8f48f4e21c7aa4 Mon Sep 17 00:00:00 2001 From: A Tobey Date: Mon, 9 Nov 2026 10:19:10 -0500 Subject: [PATCH 1/3] =?UTF-8?q?docs(release):=20document=20the=20rc=20?= =?UTF-8?q?=E2=86=92=20final=20procedure,=20checks=20and=20recovery?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Why: Amy: "let's make sure it's documented in README.md and (briefly) AGENTS.md". The v0.6.0 release needed three attempts and steps that were not documented. Approach: README "Releases" now has the procedure (CHANGELOG, rc tag, check, final tag on the same commit, check), recovery for a 401 from the tap and a ghcr permission_denied, the tap token command that tests before it stores, and the sha256-* install box note. AGENTS.md has short steps and two hazards. Learned: kaibo review: an rc run still needs the secret (the preflight checks it), release.yml runs no tests, and `gh release view` has no isLatest field. Next: The next release follows this text. Co-Authored-By: Claude Opus 5.5 🤖 Reviewed by DeepSeek (deepseek-flash) via kaibo --- AGENTS.md | 14 +++++-- README.md | 110 ++++++++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 100 insertions(+), 24 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ccb72e0..4cae359 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -214,7 +214,7 @@ otel-cli uses semantic versioning. Before 1.0, a minor release can break compati A `v*` tag push runs `.github/workflows/release.yml`. GoReleaser (`.goreleaser.yml`) makes the binaries, packages, SBOM, signatures, GitHub release and Homebrew formula. -The workflow then builds, signs, attests and tags the ghcr.io image. +The workflow then builds, signs, attests and tags the `ghcr.io/tobert/otel-cli` image. - A `-rc.N` tag makes a GitHub prerelease. It does not update the Homebrew tap or `latest`. @@ -223,10 +223,16 @@ The workflow then builds, signs, attests and tags the ghcr.io image. To release: 1. Update CHANGELOG.md and merge it to main. -2. Tag main: `git tag v0.X.Y && git push origin v0.X.Y`. -3. Watch the `release` workflow. +2. Tag `v0.X.Y-rc.1` on main. Watch the run. Check that the image reports the rc version. +3. Tag `v0.X.Y` on the same commit. Check the release, the tap and the image. -README.md, "Releases" has the full procedure and the required secret. +- Do not move or reuse a published tag. Release the next patch version. +- If the Homebrew step fails, the GitHub release exists. Fix the token, then run + `gh run rerun `. +- Only Amy can set the tap token. Ask her. + +The "Releases" section of README.md has the full procedure, the verification commands +and the recovery steps. ## Attribution diff --git a/README.md b/README.md index 91aab48..6038d10 100644 --- a/README.md +++ b/README.md @@ -342,37 +342,107 @@ We welcome contributions! This project uses agent-assisted development starting ## Releases -Releases are cut by GitHub Actions: pushing a `v*` tag runs -[release.yml](.github/workflows/release.yml), which drives goreleaser -([.goreleaser.yml](.goreleaser.yml)) to build every platform, publish the GitHub -release with archives, apk/deb/rpm packages, checksums and an SPDX SBOM, push the -Homebrew formula to [tobert/homebrew-otel-cli](https://github.com/tobert/homebrew-otel-cli), -and then builds, signs, attests and tags the multiarch `ghcr.io/tobert/otel-cli` image. -Everything is signed keylessly with cosign and carries SLSA build provenance; see +A `v*` tag push runs [release.yml](.github/workflows/release.yml). GoReleaser +([.goreleaser.yml](.goreleaser.yml)) builds every platform and publishes the GitHub +release: archives, apk/deb/rpm packages, checksums and an SPDX SBOM. It also pushes +the Homebrew formula to [tobert/homebrew-otel-cli](https://github.com/tobert/homebrew-otel-cli). +The workflow then builds, signs, attests and tags the multiarch `ghcr.io/tobert/otel-cli` +image. cosign signs `checksums.txt` and the image keylessly. Each file in +`checksums.txt` and the image have SLSA build provenance. See [Verify a download](#verify-a-download). -To cut a release: +A release candidate (rc) tag, `v0.X.Y-rc.N`, makes a GitHub prerelease. An rc does not +update the Homebrew tap or the `latest` and `X.Y` image tags. + +### Make a release + +1. Update CHANGELOG.md in a PR and merge it. Use the date of the final tag. +2. Tag an rc on main and watch the run: + + ```shell + git checkout main && git pull --ff-only + git tag v0.X.Y-rc.1 && git push origin v0.X.Y-rc.1 + gh run watch + ``` + +3. Check the rc. The image must report the rc version: + + ```shell + docker run --rm ghcr.io/tobert/otel-cli:0.X.Y-rc.1 version + gh attestation verify oci://ghcr.io/tobert/otel-cli:0.X.Y-rc.1 -R tobert/otel-cli + ``` + +4. Tag the final release on the same commit as the rc: + + ```shell + git tag v0.X.Y && git push origin v0.X.Y + gh run watch + ``` + +5. Check the final release. These commands print `v0.X.Y`, `otel-cli v0.X.Y` and + `0.X.Y`: + + ```shell + gh release list --json tagName,isLatest --jq '.[] | select(.isLatest) | .tagName' + gh api repos/tobert/homebrew-otel-cli/commits --jq '.[0].commit.message' + docker run --rm ghcr.io/tobert/otel-cli:latest version + ``` + +An rc run stops if the tap token secret is empty, but it does not push to the tap. The +final release is the first run that uses the token. + +The rc tag and the final tag can be on the same commit. The workflow gives GoReleaser +the pushed tag in `GORELEASER_CURRENT_TAG`. The run stops before the image push if the +binary version does not match the tag. + +### If a release run fails + +Do not move or reuse a published tag. The Go module proxy keeps the first commit of +each tag. To change the code, release the next patch version. + +- **The Homebrew step fails with `401 Bad credentials`.** The GitHub release exists. + The tap token is not valid. Set a new token (see below), then run + `gh run rerun `. GoReleaser replaces the existing release assets. +- **The image push fails with `denied: permission_denied`.** The ghcr package is not + linked to this repository. In the package settings, open "Manage Actions access" and + give `tobert/otel-cli` the Write role. Then run `gh run rerun `. + +### The tap token + +The workflow needs the repository secret `HOMEBREW_TAP_GITHUB_TOKEN`. Use a +fine-grained personal access token with *Contents: read and write* on +`tobert/homebrew-otel-cli` only. `GITHUB_TOKEN` covers the release and the container +registry. + +Set the secret with this command. It tests the token against the tap before it stores +it. It also keeps the token out of the shell history: ```shell -git checkout main && git pull --rebase # release tags come off main -# update CHANGELOG.md for the new version and merge that first -git tag v0.6.0 # a -rc.N suffix makes a GitHub prerelease and skips the tap -git push origin v0.6.0 # the tag push triggers release.yml -gh run watch # optional: follow along +read -rs T && GH_TOKEN="$T" gh api repos/tobert/homebrew-otel-cli --jq '.permissions' \ + && printf '%s' "$T" | gh secret set HOMEBREW_TAP_GITHUB_TOKEN --repo tobert/otel-cli; unset T ``` -To smoke the whole matrix without publishing, run the workflow by hand from the -Actions tab (`workflow_dispatch`), or locally: +A good token prints `"push": true`. The workflow stops a tag run if the secret is +empty, but it cannot test the token. A token that is not valid or has expired fails +only at the Homebrew step of a final release. + +### Test the release build + +Run the workflow by hand from the Actions tab (`workflow_dispatch`). This snapshot run +builds every artifact and smoke-tests the binary and the image. It publishes nothing. +CI runs the tests, not this workflow. You can also run a snapshot locally: ```shell goreleaser release --snapshot --clean --skip=publish,sign,sbom ``` -The workflow needs one repository secret, `HOMEBREW_TAP_GITHUB_TOKEN`: a -fine-grained personal access token with *Contents: read and write* on the tap -repository only. `GITHUB_TOKEN` covers the release and the container registry. -The workflow refuses to start a tagged release without it rather than fail after -the GitHub release is already published. +A snapshot does not need a tag on the current commit. It does not use the tap token. + +### The package page + +The install command on the ghcr package page can show a `sha256-*` tag. That tag holds +the cosign signature and attestation, not an image. Pull a version tag, for example +`ghcr.io/tobert/otel-cli:0.6.0`. ## License From db8de3db0428d187b219957ffa2f1fa8d8bf4ce9 Mon Sep 17 00:00:00 2001 From: A Tobey Date: Mon, 9 Nov 2026 10:29:01 -0500 Subject: [PATCH 2/3] docs(agents): say maintainer, not Amy, for the tap token Why: Amy: "should replace 'Amy' with @tobert or 'maintainers'". Approach: AGENTS.md already says "Ask a maintainer"; use the same term. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 4cae359..8551adb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -229,7 +229,7 @@ To release: - Do not move or reuse a published tag. Release the next patch version. - If the Homebrew step fails, the GitHub release exists. Fix the token, then run `gh run rerun `. -- Only Amy can set the tap token. Ask her. +- Only a maintainer can set the tap token. Ask a maintainer. The "Releases" section of README.md has the full procedure, the verification commands and the recovery steps. From 516ebeaff7f644e53a2c5e619fad898eb45817a2 Mon Sep 17 00:00:00 2001 From: A Tobey Date: Mon, 9 Nov 2026 10:30:00 -0500 Subject: [PATCH 3/3] docs(release): cut README and AGENTS.md to pointers Why: Amy: "you added way too much to the README.md, just say where the process is, say a lot less, we can infer most of it and just need pointers". Approach: README points to release.yml and .goreleaser.yml, whose comments explain each step, and lists four rules the code does not show. The token scope is in release.yml:62-64 and .goreleaser.yml:133-134. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 12 ++----- README.md | 106 ++++-------------------------------------------------- 2 files changed, 9 insertions(+), 109 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8551adb..e75ec9b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -223,16 +223,10 @@ The workflow then builds, signs, attests and tags the `ghcr.io/tobert/otel-cli` To release: 1. Update CHANGELOG.md and merge it to main. -2. Tag `v0.X.Y-rc.1` on main. Watch the run. Check that the image reports the rc version. -3. Tag `v0.X.Y` on the same commit. Check the release, the tap and the image. +2. Tag `v0.X.Y-rc.1` on main and watch the `release` workflow. +3. Tag `v0.X.Y` on the same commit. -- Do not move or reuse a published tag. Release the next patch version. -- If the Homebrew step fails, the GitHub release exists. Fix the token, then run - `gh run rerun `. -- Only a maintainer can set the tap token. Ask a maintainer. - -The "Releases" section of README.md has the full procedure, the verification commands -and the recovery steps. +Only a maintainer can set the tap token. README.md, "Releases" has the other rules. ## Attribution diff --git a/README.md b/README.md index 6038d10..5d3cdf6 100644 --- a/README.md +++ b/README.md @@ -342,107 +342,13 @@ We welcome contributions! This project uses agent-assisted development starting ## Releases -A `v*` tag push runs [release.yml](.github/workflows/release.yml). GoReleaser -([.goreleaser.yml](.goreleaser.yml)) builds every platform and publishes the GitHub -release: archives, apk/deb/rpm packages, checksums and an SPDX SBOM. It also pushes -the Homebrew formula to [tobert/homebrew-otel-cli](https://github.com/tobert/homebrew-otel-cli). -The workflow then builds, signs, attests and tags the multiarch `ghcr.io/tobert/otel-cli` -image. cosign signs `checksums.txt` and the image keylessly. Each file in -`checksums.txt` and the image have SLSA build provenance. See -[Verify a download](#verify-a-download). +A `v*` tag push runs [release.yml](.github/workflows/release.yml) and +[.goreleaser.yml](.goreleaser.yml). The comments in those files explain each step. -A release candidate (rc) tag, `v0.X.Y-rc.N`, makes a GitHub prerelease. An rc does not -update the Homebrew tap or the `latest` and `X.Y` image tags. - -### Make a release - -1. Update CHANGELOG.md in a PR and merge it. Use the date of the final tag. -2. Tag an rc on main and watch the run: - - ```shell - git checkout main && git pull --ff-only - git tag v0.X.Y-rc.1 && git push origin v0.X.Y-rc.1 - gh run watch - ``` - -3. Check the rc. The image must report the rc version: - - ```shell - docker run --rm ghcr.io/tobert/otel-cli:0.X.Y-rc.1 version - gh attestation verify oci://ghcr.io/tobert/otel-cli:0.X.Y-rc.1 -R tobert/otel-cli - ``` - -4. Tag the final release on the same commit as the rc: - - ```shell - git tag v0.X.Y && git push origin v0.X.Y - gh run watch - ``` - -5. Check the final release. These commands print `v0.X.Y`, `otel-cli v0.X.Y` and - `0.X.Y`: - - ```shell - gh release list --json tagName,isLatest --jq '.[] | select(.isLatest) | .tagName' - gh api repos/tobert/homebrew-otel-cli/commits --jq '.[0].commit.message' - docker run --rm ghcr.io/tobert/otel-cli:latest version - ``` - -An rc run stops if the tap token secret is empty, but it does not push to the tap. The -final release is the first run that uses the token. - -The rc tag and the final tag can be on the same commit. The workflow gives GoReleaser -the pushed tag in `GORELEASER_CURRENT_TAG`. The run stops before the image push if the -binary version does not match the tag. - -### If a release run fails - -Do not move or reuse a published tag. The Go module proxy keeps the first commit of -each tag. To change the code, release the next patch version. - -- **The Homebrew step fails with `401 Bad credentials`.** The GitHub release exists. - The tap token is not valid. Set a new token (see below), then run - `gh run rerun `. GoReleaser replaces the existing release assets. -- **The image push fails with `denied: permission_denied`.** The ghcr package is not - linked to this repository. In the package settings, open "Manage Actions access" and - give `tobert/otel-cli` the Write role. Then run `gh run rerun `. - -### The tap token - -The workflow needs the repository secret `HOMEBREW_TAP_GITHUB_TOKEN`. Use a -fine-grained personal access token with *Contents: read and write* on -`tobert/homebrew-otel-cli` only. `GITHUB_TOKEN` covers the release and the container -registry. - -Set the secret with this command. It tests the token against the tap before it stores -it. It also keeps the token out of the shell history: - -```shell -read -rs T && GH_TOKEN="$T" gh api repos/tobert/homebrew-otel-cli --jq '.permissions' \ - && printf '%s' "$T" | gh secret set HOMEBREW_TAP_GITHUB_TOKEN --repo tobert/otel-cli; unset T -``` - -A good token prints `"push": true`. The workflow stops a tag run if the secret is -empty, but it cannot test the token. A token that is not valid or has expired fails -only at the Homebrew step of a final release. - -### Test the release build - -Run the workflow by hand from the Actions tab (`workflow_dispatch`). This snapshot run -builds every artifact and smoke-tests the binary and the image. It publishes nothing. -CI runs the tests, not this workflow. You can also run a snapshot locally: - -```shell -goreleaser release --snapshot --clean --skip=publish,sign,sbom -``` - -A snapshot does not need a tag on the current commit. It does not use the tap token. - -### The package page - -The install command on the ghcr package page can show a `sha256-*` tag. That tag holds -the cosign signature and attestation, not an image. Pull a version tag, for example -`ghcr.io/tobert/otel-cli:0.6.0`. +- Tag `v0.X.Y-rc.1` first. An rc does not update the Homebrew tap or `latest`. +- The tap push needs the repository secret `HOMEBREW_TAP_GITHUB_TOKEN`. +- If a run fails after the GitHub release exists, fix the cause and run `gh run rerun`. +- Do not move a published tag. Release the next patch version. ## License