release: harden GitHub release automation

Author: brianmhunt

.github/workflows/github-release-repair.yml

@@ -0,0 +1,39 @@
+name: Create GitHub Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Release version without the leading v (for example 4.0.1)
+        required: true
+        type: string
+      target_sha:
+        description: Commit SHA to tag and release
+        required: true
+        type: string
+
+jobs:
+  create-github-release:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Create GitHub release if missing
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ inputs.version }}
+          TARGET_SHA: ${{ inputs.target_sha }}
+        run: |
+          tag="v${VERSION}"
+          if gh release view "$tag" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            echo "GitHub release $tag already exists; skipping."
+            exit 0
+          fi
+
+          gh release create "$tag" \
+            --repo "$GITHUB_REPOSITORY" \
+            --target "$TARGET_SHA" \
+            --title "TKO ${VERSION}" \
+            --generate-notes

.github/workflows/release.yml

@@ -112,10 +112,12 @@ jobs:
       - name: Checkout code
         # actions/checkout v6.0.2
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          persist-credentials: false
 
       - name: Determine release version
         id: version
-        run: echo "version=$(node -p 'require(\"./lerna.json\").version')" >> "$GITHUB_OUTPUT"
+        run: echo "version=$(node -p 'require(\"./builds/reference/package.json\").version')" >> "$GITHUB_OUTPUT"
 
       - name: Create GitHub release if missing
         env:

AGENTS.md

@@ -107,6 +107,7 @@ GitHub Actions workflows (`.github/workflows/`):
 | `lint-and-typecheck.yml` | PRs | Prettier + ESLint + tsc (combined) |
 | `publish-check.yml` | PRs | Verify packages are publishable |
 | `release.yml` | Push to main | Changeset version PRs + npm publish + GitHub release |
+| `github-release-repair.yml` | Manual | Recreate or repair a GitHub release/tag boundary after publish |
 | `deploy-docs.yml` | Push to main | Deploy tko.io to GitHub Pages |
 | `codeql-analysis.yml` | Weekly + main push | Security scanning |
 
@@ -128,6 +129,7 @@ This creates a changeset file in `.changeset/` that gets committed with your PR.
 3. Review the PR (it bumps versions and updates changelogs)
 4. Merge it to publish to npm via GitHub Actions OIDC trusted publishing
 5. After a successful publish, CI creates the matching GitHub Release and tag
+6. If release creation ever needs repair after publish, run `github-release-repair.yml` with the version and merged commit SHA
 
 Avoid manual workstation publishes. If release CI is unavailable, fix the
 workflow or npm trusted publisher configuration rather than bypassing it with a

README.md

@@ -56,6 +56,7 @@ It's available as `@tko/build.knockout`, and over CDN:
 | $ `make test-headless` | Run all tests with chromium. See below. |
 | $ `npx changeset add` | Add a changeset for package behavior changes in your PR |
 | Release workflow | On merge to `main`, CI opens or updates a version PR; when that version PR is merged and there are no remaining changesets, CI publishes from GitHub Actions via npm trusted publishing and creates the matching GitHub Release |
+| GitHub release repair | Manual workflow to recreate the GitHub Release/tag boundary if publish succeeded but release creation needs a retry |
 | $ `make test-coverage` | Run all tests and create a code coverage report |
 
 Checkout the `Makefile` for more commands that can be executed with `make {command}`.

plans/build-and-release-certainty.md

@@ -74,6 +74,7 @@ to npm.
 - After a successful publish, creates the matching GitHub Release and tag
 - Uses npm trusted publishing via GitHub Actions OIDC
 - Requires trusted publisher configuration for the public `@tko/*` packages on npm
+- Includes a manual `github-release-repair.yml` workflow for rerunnable release/tag repair if GitHub release creation ever needs a retry after publish
 
 ---