feat(release): start a release by hand, not only by pushing a tag

Pushing a vX.Y.Z tag was the only way in, which left no way to re-run a release whose tag had already published before the job died — the second push is a no-op, so the only recourse was deleting and moving a tag people may already have.

Add workflow_dispatch with a tag input. It is the same job under the same gates: check-version.sh --tag still fails the run when the tag disagrees with version.go, the Makefile or the Formula, so the bump must be committed either way.

The one thing a manual run must not get wrong is which commit it builds. A dispatch starts on the branch chosen in the UI, so when the tag already exists the job checks that tag out and builds from it — otherwise it would publish today's main under a tag naming an older commit. A tag that does not exist yet is created on the selected branch.

The input is validated against the vX.Y.Z shape before it reaches git and is passed by env rather than interpolated into the script.

Author: piotrlaczkowski

.github/workflows/release.yml

@@ -4,6 +4,23 @@ on:
   push:
     tags:
       - "v*"
+  # The same release, started by hand from the Actions tab. Pushing a tag stays
+  # the normal path (RELEASE.md step 2); this is for the two cases where there is
+  # no push to react to: re-running a release whose tag is already published but
+  # whose job failed partway, and cutting one from the UI without a local
+  # checkout. It changes nothing about what a release IS — the version still has
+  # to be committed, because check-version.sh below fails the run when the tag
+  # disagrees with version.go, the Makefile or the Formula.
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: >-
+          Release tag, e.g. v0.25.0. The bump must already be committed
+          (scripts/prepare-release.sh writes version.go, the Makefile and the
+          Formula). If this tag already exists the release is rebuilt from it;
+          if not, it is created on the branch selected above.
+        required: true
+        type: string
 
 permissions:
   contents: write
@@ -27,6 +44,33 @@ jobs:
         with:
           fetch-depth: 0
 
+      # A manual run starts on the BRANCH picked in the Actions tab, not on a
+      # tag. When the tag already exists — re-running a release that published
+      # its tag and then failed — build from that tag: otherwise this job would
+      # publish whatever main happens to be now under a tag pointing at an older
+      # commit, and the assets would not be the release they claim to be. When
+      # the tag is new, stay on the selected ref; the Create GitHub Release step
+      # creates the tag here. fetch-depth: 0 above is what makes the tag local.
+      - name: Resolve the release tag (manual runs)
+        if: github.event_name == 'workflow_dispatch'
+        env:
+          TAG: ${{ inputs.tag }}
+        run: |
+          set -euo pipefail
+          # Validated before it reaches git, and passed by env rather than
+          # interpolated into this script.
+          if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
+            echo "::error::'${TAG}' is not a vX.Y.Z release tag (expected e.g. v0.25.0)"
+            exit 1
+          fi
+          if git rev-parse -q --verify "refs/tags/${TAG}^{commit}" >/dev/null; then
+            echo "tag ${TAG} already exists — building from it, not from ${GITHUB_REF_NAME}"
+            git checkout --detach "refs/tags/${TAG}"
+          else
+            echo "tag ${TAG} is new — it will be created on ${GITHUB_REF_NAME} at this commit"
+          fi
+          git log -1 --format='building %h %s'
+
       - name: Set up Go
         uses: actions/setup-go@v7
         with:
@@ -42,9 +86,19 @@ jobs:
 
       - name: Extract version
         id: ver
+        env:
+          # Empty on a tag push, the dispatch input on a manual run. By env, not
+          # interpolated into the script body.
+          DISPATCH_TAG: ${{ inputs.tag }}
         run: |
           set -euo pipefail
-          TAG="${GITHUB_REF_NAME}"
+          # On a manual run GITHUB_REF_NAME is the branch that was selected, so
+          # the tag has to come from the input instead.
+          if [[ "${GITHUB_EVENT_NAME}" == "workflow_dispatch" ]]; then
+            TAG="${DISPATCH_TAG}"
+          else
+            TAG="${GITHUB_REF_NAME}"
+          fi
           VERSION="${TAG#v}"
           if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
             echo "::error::tag ${TAG} is not a vX.Y.Z release tag" >&2

RELEASE.md

@@ -101,6 +101,24 @@ git push origin v0.20.0          # this is what starts the release
 Pushing the tag is the point of no return for the automation. Everything before it is
 reversible with `git tag -d` and `git reset`.
 
+### Starting it by hand instead
+
+The same workflow can be started from **Actions → Release → Run workflow**, which asks for
+the tag (`v0.20.0`) and the branch to run from. Use it when there is no push for the
+automation to react to:
+
+- **Re-running a release that failed partway.** The tag is already published, so
+  `git push origin v0.20.0` does nothing a second time. A manual run notices the tag
+  already exists and builds **from that tag**, not from whatever `main` has become since —
+  so the assets still match the commit the tag names. (If you need to move the tag itself,
+  that is the rollback in step 6, not this.)
+- **Cutting a release without a local checkout.**
+
+It is the same job with the same gates: the bump must already be committed, because
+`check-version.sh --tag` still fails the run when the tag disagrees with `version.go`, the
+Makefile or the Formula. A tag that does not exist yet is created on the branch you
+selected.
+
 ---
 
 ## 3. What CI does (watch it, do not skip ahead)
@@ -233,7 +251,10 @@ git tag -d v0.20.0
 git reset --hard origin/main
 ```
 
-**After the tag is pushed but CI failed** — no release exists, so just fix and re-tag:
+**After the tag is pushed but CI failed** — no release exists. If the tree is fine and the
+run died on something transient (a registry timeout, a runner hiccup), just start it again
+from **Actions → Release → Run workflow** with the same tag; it rebuilds from that tag.
+If the tree itself is at fault, fix and re-tag:
 
 ```bash
 git push --delete origin v0.20.0