fix: release flow + docs (pinchtab#371)

luigiagent · luigi-agosti · web-flow · commit ce7efa1c3d56 · 2026-03-22T01:05:14.000+01:00
Co-authored-by: Luigi Agosti &lt;luigi@tengio.com&gt;
diff --git a/.github/workflows/release-manual-publish.yml b/.github/workflows/release-manual-publish.yml
@@ -3,60 +3,68 @@ name: Release / Manual Publish
 on:
   workflow_dispatch:
     inputs:
-      version:
-        description: 'Release version (e.g. 0.8.0, without v prefix)'
+      tag:
+        description: 'Existing release tag to publish (e.g. v0.8.0)'
         required: true
-      ref:
-        description: 'Git ref to tag. Defaults to main.'
-        required: false
-        default: 'main'
 
 permissions:
-  contents: write
+  contents: read
 
 concurrency:
-  group: release-manual-${{ inputs.version }}
+  group: release-manual-${{ inputs.tag }}
   cancel-in-progress: false
 
 jobs:
   validate:
-    uses: ./.github/workflows/reusable-validate-release.yml
-    with:
-      version: ${{ inputs.version }}
-      ref: ${{ inputs.ref }}
-
-  create-tag:
-    name: Create Release Tag
-    needs: validate
+    name: Validate Existing Tag
     runs-on: ubuntu-latest
-    environment:
-      name: release-approval
-    permissions:
-      contents: write
+    outputs:
+      tag: ${{ steps.meta.outputs.tag }}
+      ref: ${{ steps.meta.outputs.ref }}
     steps:
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-          ref: ${{ needs.validate.outputs.sha }}
 
-      - name: Create and push tag
+      - name: Normalize and validate tag
+        id: meta
         run: |
-          TAG="${{ needs.validate.outputs.tag }}"
+          TAG="${{ inputs.tag }}"
+          if [ "${TAG#v}" = "$TAG" ]; then
+            TAG="v$TAG"
+          fi
 
-          if git ls-remote --exit-code --tags origin "refs/tags/$TAG" >/dev/null 2>&1; then
-            echo "tag $TAG already exists on origin" >&2
+          git fetch --tags origin
+          if ! git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+            echo "tag $TAG not found on origin" >&2
             exit 1
           fi
 
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git tag -a "$TAG" -m "Release $TAG (manual)"
-          git push origin "refs/tags/$TAG"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "ref=refs/tags/$TAG" >> "$GITHUB_OUTPUT"
 
+  approval:
+    name: Manual Approval
+    needs: validate
+    runs-on: ubuntu-latest
+    environment:
+      name: release-approval
+    steps:
       - name: Summarize
         run: |
-          echo "## Release Tag Created (Manual)" >> "$GITHUB_STEP_SUMMARY"
+          echo "## Manual Publish Approval" >> "$GITHUB_STEP_SUMMARY"
           echo "- Tag: ${{ needs.validate.outputs.tag }}" >> "$GITHUB_STEP_SUMMARY"
-          echo "- Commit: \`${{ needs.validate.outputs.sha }}\`" >> "$GITHUB_STEP_SUMMARY"
-          echo "" >> "$GITHUB_STEP_SUMMARY"
-          echo "The **Release / Publish** workflow will trigger automatically." >> "$GITHUB_STEP_SUMMARY"
+
+  publish:
+    name: Publish Existing Tag
+    needs:
+      - validate
+      - approval
+    permissions:
+      contents: write
+      packages: write
+    uses: ./.github/workflows/reusable-release-publish.yml
+    with:
+      ref: ${{ needs.validate.outputs.ref }}
+      tag: ${{ needs.validate.outputs.tag }}
+    secrets: inherit
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -1,4 +1,4 @@
-name: Release / Prepare
+name: Release
 
 on:
   workflow_dispatch:
@@ -222,3 +222,19 @@ jobs:
           echo "## Release Tag Created" >> "$GITHUB_STEP_SUMMARY"
           echo "- Tag: ${{ needs.validate.outputs.tag }}" >> "$GITHUB_STEP_SUMMARY"
           echo "- Commit: \`${{ needs.validate.outputs.sha }}\`" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "Publishing continues in this workflow from the approved tag." >> "$GITHUB_STEP_SUMMARY"
+
+  publish:
+    name: Publish Release
+    needs:
+      - validate
+      - create-tag
+    permissions:
+      contents: write
+      packages: write
+    uses: ./.github/workflows/reusable-release-publish.yml
+    with:
+      ref: refs/tags/${{ needs.validate.outputs.tag }}
+      tag: ${{ needs.validate.outputs.tag }}
+    secrets: inherit
diff --git a/.github/workflows/reusable-release-publish.yml b/.github/workflows/reusable-release-publish.yml
@@ -1,8 +1,16 @@
-name: Release / Publish
+name: Reusable / Release Publish
 
 on:
-  push:
-    tags: ['v*']
+  workflow_call:
+    inputs:
+      ref:
+        description: 'Git ref to publish from (for example refs/tags/v0.8.0)'
+        required: true
+        type: string
+      tag:
+        description: 'Release tag with v prefix'
+        required: true
+        type: string
 
 env:
   GORELEASER_VERSION: v2.14.3
@@ -11,7 +19,7 @@ permissions:
   contents: write
 
 concurrency:
-  group: release-${{ github.ref_name }}
+  group: release-${{ inputs.tag }}
   cancel-in-progress: false
 
 jobs:
@@ -24,7 +32,7 @@ jobs:
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
-          ref: ${{ github.ref }}
+          ref: ${{ inputs.ref }}
 
       - uses: actions/setup-go@v6
         with:
@@ -54,7 +62,7 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          ref: ${{ github.ref }}
+          ref: ${{ inputs.ref }}
 
       - uses: actions/setup-node@v6
         with:
@@ -64,7 +72,7 @@ jobs:
       - name: Extract version
         id: version
         run: |
-          TAG="${{ github.ref_name }}"
+          TAG="${{ inputs.tag }}"
           VERSION="${TAG#v}"
           echo "tag=$TAG" >> "$GITHUB_OUTPUT"
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
@@ -106,12 +114,12 @@ jobs:
     steps:
       - uses: actions/checkout@v6
         with:
-          ref: ${{ github.ref }}
+          ref: ${{ inputs.ref }}
 
       - name: Extract Docker metadata
         id: meta
         run: |
-          TAG="${{ github.ref_name }}"
+          TAG="${{ inputs.tag }}"
           VERSION="${TAG#v}"
           echo "tag=$TAG" >> "$GITHUB_OUTPUT"
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
@@ -155,6 +163,6 @@ jobs:
       - npm
     uses: ./.github/workflows/reusable-publish-skill.yml
     with:
-      version: ${{ github.ref_name }}
+      version: ${{ inputs.tag }}
     secrets:
       CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}
diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@
 <p align="center">
   <strong>PinchTab</strong><br/>
   <strong>Browser control for AI agents</strong><br/>
-  12MB Go binary • HTTP API • Token-efficient
+  Small Go binary • HTTP API • Token-efficient
 </p>
 
 
@@ -16,7 +16,7 @@
     </td>
     <td align="left" valign="middle">
       <a href="https://github.com/pinchtab/pinchtab/releases/latest"><img src="https://img.shields.io/github/v/release/pinchtab/pinchtab?style=flat-square&color=FFD700" alt="Release"/></a><br/>
-      <a href="https://github.com/pinchtab/pinchtab/actions/workflows/go-verify.yml"><img src="https://img.shields.io/github/actions/workflow/status/pinchtab/pinchtab/go-verify.yml?branch=main&style=flat-square&label=Build" alt="Build"/></a><br/>
+      <a href="https://github.com/pinchtab/pinchtab/actions/workflows/ci-go.yml"><img src="https://img.shields.io/github/actions/workflow/status/pinchtab/pinchtab/ci-go.yml?branch=main&style=flat-square&label=Go%20CI" alt="Go CI"/></a><br/>
       <img src="https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat-square&logo=go&logoColor=white" alt="Go 1.25+"/><br/>
       <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square" alt="License"/></a>
     </td>
diff --git a/RELEASE.md b/RELEASE.md
@@ -66,15 +66,15 @@ grep -A 2 "^release:" .goreleaser.yml
 - ✅ `checksum:` generates `checksums.txt` (used by npm postinstall verification)
 - ✅ `release:` points to GitHub (uploads everything automatically)
 
-**Ready to release.** The recommended path is now the manual `Prepare Release` workflow, which runs the full verification suite, pauses for approval, and only then creates the tag.
+**Ready to release.** The recommended path is now the manual `Release` workflow, which runs the full verification suite, pauses for approval, creates the tag, and then finishes publishing in the same run.
 
 ## Releasing
 
 ## Manual Release Flow
 
 1. Choose the branch, tag, or SHA you want to release.
-   `Prepare Release` now validates the requested version format and tag availability, then rewrites the npm package version inside the CI workspace for the dry-run steps.
-2. Open **Actions → Prepare Release**.
+   `Release` now validates the requested version format and tag availability, then rewrites the npm package version inside the CI workspace for the dry-run steps.
+2. Open **Actions → Release**.
 3. Run it with:
    - `version`: the release version, for example `0.8.0`
    - `ref`: the branch, tag, or SHA you want to release
@@ -88,13 +88,21 @@ grep -A 2 "^release:" .goreleaser.yml
    - GoReleaser snapshot
    - `npm publish --dry-run`
 5. After those pass, GitHub pauses at the `release-approval` environment gate.
-6. Approve the run. The workflow creates and pushes `v0.8.0` from the exact tested commit SHA.
-7. That tag triggers the `Release` workflow automatically.
+6. Approve the run. The workflow creates and pushes `v0.8.0` from the exact tested commit SHA, then continues publishing from that tag in the same run.
+7. Monitor the remaining publish jobs in the same workflow run:
+   - GitHub release binaries
+   - npm publish
+   - Docker image publish
+   - ClawHub skill publish
 
 ### Required GitHub setup
 
 Configure a protected environment named `release-approval` with the required reviewers for the manual gate to be effective.
 
+### Recovery publish
+
+If a tag already exists and you need to retry publishing, use **Actions → Release / Manual Publish** with the existing tag, for example `v0.8.0`.
+
 ## Pipeline details
 
 ### 1. Goreleaser (Go binary) — CRITICAL for npm
diff --git a/docs/guides/contributing.md b/docs/guides/contributing.md
@@ -356,7 +356,7 @@ Workflows follow a naming convention:
 |--------|---------|---------|
 | `ci-*` | Automatic checks on PR/push | `ci-go.yml` → **CI / Go** |
 | `reusable-*` | Building blocks (`workflow_call` only) | `reusable-e2e.yml` → **Reusable / E2E** |
-| `release-*` | Release pipeline | `release-prepare.yml` → **Release / Prepare** |
+| `release-*` | Release pipeline | `release.yml` → **Release** |
 
 ### CI Checks
 
@@ -375,11 +375,10 @@ Run automatically on pull requests and/or push to `main`:
 
 | Workflow | Trigger | What it does |
 |----------|---------|--------------|
-| **Release / Prepare** | Manual | Runs all checks + E2E → manual approval gate → creates tag |
-| **Release / Publish** | Tag push (`v*`) | GoReleaser + npm + Docker + ClawHub skill |
-| **Release / Manual Publish** | Manual | Validates + creates tag (bypasses Prepare) → triggers Publish |
+| **Release** | Manual | Runs all checks + E2E → manual approval gate → creates tag → publishes binaries, npm, Docker, and skill |
+| **Release / Manual Publish** | Manual | Publishes an existing tag as a recovery path |
 
-In **Release / Prepare**, E2E and Docker smoke failures are non-blocking — they surface
+In **Release**, E2E and Docker smoke failures are non-blocking — they surface
 in the approval summary so you can decide whether to proceed. Core checks (Go, Dashboard,
 Docs, npm, publish dry-run) must pass for the approval gate to appear.
 
diff --git a/install.sh b/install.sh
@@ -12,7 +12,7 @@ ERROR='\033[38;2;230;57;70m'        # red #e63946
 MUTED='\033[38;2;90;100;128m'       # text-muted #5a6480
 NC='\033[0m' # No Color
 
-TAGLINE="12MB binary. Zero config. Accessibility-first browser control."
+TAGLINE="Small binary. Zero config. Accessibility-first browser control."
 
 cleanup_tmpfiles() {
     local f
diff --git a/skills/pinchtab-dev/SKILL.md b/skills/pinchtab-dev/SKILL.md
@@ -5,7 +5,7 @@ description: Develop and contribute to the PinchTab project. Use when working on
 
 # PinchTab Development
 
-PinchTab is a browser control server for AI agents — 12MB Go binary with HTTP API.
+PinchTab is a browser control server for AI agents — Small Go binary with HTTP API.
 
 ## Project Location
 
diff --git a/skills/pinchtab/TRUST.md b/skills/pinchtab/TRUST.md
@@ -38,7 +38,7 @@ Binaries are built automatically from tagged commits via GitHub Actions (publicl
 - **Releases**: https://github.com/pinchtab/pinchtab/releases
 - **Latest**: v0.8.4 (Mar 2026)
 
-If you're concerned, audit the source—it's 12MB, zero external dependencies, mostly Go stdlib.
+If you're concerned, audit the source—it's ~15MB, zero external dependencies, mostly Go stdlib.
 
 ## VirusTotal Flag
 
