Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix: release flow + docs (#371)

luigiagentce7efa1c3d56
diff --git a/.github/workflows/release-manual-publish.yml b/.github/workflows/release-manual-publish.yml
index 06982a38..f8a0c84f 100644
--- 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-prepare.yml b/.github/workflows/release.yml
similarity index 93%
rename from .github/workflows/release-prepare.yml
rename to .github/workflows/release.yml
index ab8ff304..73474737 100644
--- a/.github/workflows/release-prepare.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/release-publish.yml b/.github/workflows/reusable-release-publish.yml
similarity index 87%
rename from .github/workflows/release-publish.yml
rename to .github/workflows/reusable-release-publish.yml
index 8e691f99..0d043e4d 100644
--- a/.github/workflows/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
index d66d0606..2372f4e3 100644
--- 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
index 57bb6c90..04b4e6b6 100644
--- 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
index 96c26a9e..3f55b8ed 100644
--- 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
index 8330c010..9b278774 100755
--- 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
index 2781d390..01a299c7 100644
--- 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
index 7ad764b8..d378a42a 100644
--- 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