From f25eb06093230a3cec4592335f3507de246dd289 Mon Sep 17 00:00:00 2001
From: James <james.russo@heygen.com>
Date: Mon, 23 Mar 2026 03:41:17 +0000
Subject: [PATCH] feat(ci): add PR-based release flow with auto-tagging

---
 .github/workflows/publish.yml     | 12 ++++++-
 .github/workflows/release-tag.yml | 24 ++++++++++++++
 .github/workflows/release.yml     | 55 +++++++++++++++++++++++++++++++
 CONTRIBUTING.md                   | 34 +++++++++----------
 4 files changed, 105 insertions(+), 20 deletions(-)
 create mode 100644 .github/workflows/release-tag.yml
 create mode 100644 .github/workflows/release.yml

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 845b91f5..5e0b9e5b 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -12,7 +12,7 @@ jobs:
     timeout-minutes: 10
     environment: npm-publish
     permissions:
-      contents: read
+      contents: write
       id-token: write
     steps:
       - uses: actions/checkout@v4
@@ -41,3 +41,13 @@ jobs:
 
       - name: Publish hyperframes (CLI)
         run: pnpm --filter hyperframes publish --access public --provenance --no-git-checks
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          gh release create "v${VERSION}" \
+            --repo "${{ github.repository }}" \
+            --title "v${VERSION}" \
+            --generate-notes
diff --git a/.github/workflows/release-tag.yml b/.github/workflows/release-tag.yml
new file mode 100644
index 00000000..d9584f1c
--- /dev/null
+++ b/.github/workflows/release-tag.yml
@@ -0,0 +1,24 @@
+name: Tag Release
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+jobs:
+  tag:
+    name: Create release tag
+    if: github.event.pull_request.merged == true && startsWith(github.event.pull_request.head.ref, 'release/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version and create tag
+        run: |
+          VERSION="${{ github.event.pull_request.head.ref }}"
+          VERSION="${VERSION#release/}"
+          echo "Tagging ${VERSION}"
+          git tag "${VERSION}"
+          git push origin "${VERSION}"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 00000000..dbfc8d39
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,55 @@
+name: Prepare Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (e.g., 0.2.0, 1.0.0-beta.1)"
+        required: true
+        type: string
+
+jobs:
+  prepare:
+    name: Prepare release PR
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+
+      - name: Bump versions
+        run: pnpm set-version ${{ inputs.version }}
+
+      - name: Create release PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          BRANCH="release/v${{ inputs.version }}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+          git add packages/*/package.json
+          git commit -m "chore: release v${{ inputs.version }}"
+          git push origin "$BRANCH"
+          gh pr create \
+            --title "chore: release v${{ inputs.version }}" \
+            --body "$(cat <<'BODY'
+          ## Release v${{ inputs.version }}
+
+          Bumps all packages to v${{ inputs.version }}.
+
+          **After merging**, the release tag is created automatically, which triggers npm publish.
+          BODY
+          )" \
+            --base main \
+            --head "$BRANCH"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9d949a81..81a300af 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -46,29 +46,25 @@ pnpm --filter @hyperframes/core test:hyperframe-runtime-ci  # Runtime contract t
 
 All packages use **fixed versioning** — every release bumps all packages to the same version.
 
-### Steps
+### Via GitHub UI (recommended)
 
-```bash
-# 1. Bump version, commit, and tag
-pnpm set-version 0.1.1 --tag
-
-# 2. Push to trigger the publish workflow
-git push origin main --tags
-```
-
-The `v*` tag triggers CI, which validates (build + typecheck + tests) then publishes all packages to npm with provenance attestation.
+1. Go to **Actions** → **Prepare Release** → **Run workflow**
+2. Enter the version (e.g., `0.2.0`)
+3. Click **Run workflow** — this creates a release PR
+4. Review and merge the PR
+5. Merging auto-creates the `v0.2.0` tag, which triggers npm publish and a GitHub Release
 
-### Without `--tag` (manual control)
+### Via CLI
 
 ```bash
-# 1. Bump versions only (no commit/tag)
-pnpm set-version 0.1.1
-
-# 2. Review changes, commit yourself
-git add -A
-git commit -m "chore: release v0.1.1"
-git tag v0.1.1
-git push origin main --tags
+# Bump versions, commit to a branch, create PR
+pnpm set-version 0.2.0
+git checkout -b release/v0.2.0
+git add packages/*/package.json
+git commit -m "chore: release v0.2.0"
+git push origin release/v0.2.0
+gh pr create --title "chore: release v0.2.0" --base main
+# After merge, the tag + publish happen automatically
 ```
 
 ## Reporting Issues