High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
Release Process
⚠️ CRITICAL: The npm package depends on Go binaries being in the GitHub release. The release pipeline will fail hard if goreleaser doesn't upload binaries — npm users won't get a working binary.
Pinchtab uses an automated CI/CD pipeline triggered by Git tags. When you push a tag like v0.7.0, GitHub Actions:
- Builds Go binaries — darwin-arm64, darwin-x64, linux-x64, linux-arm64, windows-x64
- Creates GitHub release — with checksums.txt for integrity verification
- Publishes to npm — TypeScript SDK with auto-download postinstall script
- Builds Docker images — linux/amd64, linux/arm64
- Publishes ClawHub packages — the skill and OpenClaw plugin publish in parallel after npm succeeds
Prerequisites
Secrets (configure once in GitHub)
Go to Settings → Secrets and variables → Actions and add:
NPM_TOKEN — npm authentication token
- Create at https://npmjs.com/settings/~/tokens
- Scope:
automation(publish + read)
DOCKERHUB_USER — Docker Hub username (if using Docker Hub)
DOCKERHUB_TOKEN — Docker Hub personal access token
CLAWHUB_TOKEN — ClawHub authentication token for publishing the skill and OpenClaw plugin
Local setup
# 1. Ensure main branch is up to date
git checkout main && git pull origin main
# 2. Merge feature branches
# (all features should be on main before tagging)
# 3. Verify version consistency
cat npm/package.json | jq .version # npm package
cat go.mod | grep "module" # Go module
git describe --tags # latest tag
Pre-Release Checklist
Goreleaser is already configured correctly. Verify before tagging:
# 1. Check builds section (compiles for all platforms)
grep -A 8 "^builds:" .goreleaser.yml
# Should output: linux/darwin/windows + amd64/arm64
# 2. Check archives use binary format (required for npm)
grep -A 5 "^archives:" .goreleaser.yml
# Should show: format: binary (not tar/zip)
# 3. Verify checksums enabled
grep "checksum:" .goreleaser.yml
# Should output: name_template: checksums.txt
# 4. Check release config
grep -A 2 "^release:" .goreleaser.yml
# Should output: GitHub owner/repo
Configuration status:
- ✅
builds:section compiles all platforms (darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-amd64, windows-arm64) - ✅
archives:outputs binaries directly:pinchtab-darwin-arm64,pinchtab-linux-x64, etc. - ✅
checksum:generateschecksums.txt(used by npm postinstall verification) - ✅
release:points to GitHub (uploads everything automatically)
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
- Choose the branch, tag, or SHA you want to release.
Releasenow validates the requested version format and tag availability, then rewrites the npm package version inside the CI workspace for the dry-run steps. - Open Actions → Release.
- Run it with:
version: the release version, for example0.8.0ref: the branch, tag, or SHA you want to release
- The workflow runs:
- Go checks
- dashboard checks
- npm package verification
- OpenClaw plugin verification
- docs verification
- full release E2E
- Docker bootstrap smoke test
- GoReleaser snapshot
npm publish --dry-run
- After those pass, GitHub pauses at the
release-approvalenvironment gate. - Approve the run. The workflow creates and pushes
v0.8.0from the exact tested commit SHA, then continues publishing from that tag in the same run. - Monitor the remaining publish jobs in the same workflow run:
- GitHub release binaries
- npm publish
- Docker image publish
- ClawHub skill publish
- ClawHub plugin 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
Triggered on v* tag push. Builds binaries and creates GitHub release.
What it does:
- ✅ Compiles for all platforms (darwin-arm64, darwin-x64, linux-x64, linux-arm64, windows-x64)
- ✅ Generates
checksums.txt(SHA256) - ✅ Uploads binaries to GitHub Releases ← Required by npm postinstall!
- Also: Docker images, changelog, etc.
⚠️ CRITICAL: npm postinstall script downloads binaries from GitHub Releases. If the release doesn't have the binaries (e.g., only Docker images), npm install pinchtab will fail silently and the binary won't be available.
Configured in: .goreleaser.yml
Verify release has binaries:
curl -s https://api.github.com/repos/pinchtab/pinchtab/releases/v0.7.0 | jq '.assets[].name'
# Should output: pinchtab-darwin-arm64, pinchtab-darwin-x64, etc.
2. npm publish
Depends on: release job (waits for goreleaser to finish)
What it does:
- Syncs version from tag (v0.7.0 → 0.7.0)
- Builds TypeScript (
npm run build) - Publishes to npm registry
- Users get postinstall script that downloads binaries from GitHub Releases
User flow on npm install pinchtab:
1. npm downloads @pinchtab/cli package
2. Runs postinstall script
3. Script detects OS/arch (darwin-arm64, linux-x64, etc.)
4. Downloads binary from GitHub release
5. Verifies SHA256 checksum
6. Stores in ~/.pinchtab/bin/0.7.0/pinchtab-<os>-<arch>
7. Makes executable
8. If ANY STEP fails → npm install fails (exit 1)
⚠️ REQUIRES: Goreleaser must have successfully uploaded binaries to GitHub release. The npm postinstall will verify this and fail hard if binaries are missing.
3. Docker
Depends on: release and npm
GitHub Actions builds the release image directly from the tagged source with docker buildx.
The workflow pushes the same multi-arch build to both GHCR and Docker Hub, but only after npm has already published successfully.
4. ClawHub packages
Depends on: release and npm
The main Release workflow publishes the Pinchtab skill and OpenClaw plugin to ClawHub automatically after npm succeeds.
They run as separate jobs at the same dependency level, so the plugin publish happens in parallel with the skill publish.
Neither ClawHub publish consumes npm artifacts or GitHub release binaries directly; the ordering is a policy choice so npm stays the first irreversible publish step.
The standalone publish workflows remain available for retries or one-off recovery publishes.
Troubleshooting
npm publish fails (403)
- Check NPM_TOKEN is set in secrets
- Verify token has
automationscope - Check you're not already published (can't overwrite existing version)
Binary checksum mismatch
- goreleaser must generate
checksums.txt - Verify
.goreleaser.ymlhaschecksum:section - Check GitHub release includes
checksums.txt
Docker push fails
- Verify DOCKERHUB_USER and DOCKERHUB_TOKEN
- Check token has permission to push
Rolling back
If something goes wrong:
# Delete the tag locally and on GitHub
git tag -d v0.7.1
git push origin :refs/tags/v0.7.1
# Delete npm version (requires owner permission)
npm unpublish [email protected]
# Revert any commits
git revert <commit>
git push origin main
# Retag when ready
git tag v0.7.1
git push origin v0.7.1
Version strategy
- Use semantic versioning: v0.7.0 (major.minor.patch)
- Tag on main branch only
- One tag = one release (all artifacts)
- npm version must match Go binary tag
Breaking changes to note in the next release
BREAKING (MCP tool surface): 14 tools collapsed into 3. An MCP client re-reads the tool list from the server on every session, so no client is stranded on the old names — but any hand-written skill or prompt that names one has to be updated:
| Removed | Replacement |
|---|---|
pinchtab_wait(ms=…) |
pinchtab_wait(for="ms", value=…) |
pinchtab_wait_for_selector(selector=…) |
pinchtab_wait(for="selector", value=…) |
pinchtab_wait_for_text(text=…) |
pinchtab_wait(for="text", value=…) |
pinchtab_wait_for_url(url=…) |
pinchtab_wait(for="url", value=…) |
pinchtab_wait_for_load(load=…) |
pinchtab_wait(for="load", value=…) |
pinchtab_wait_for_function(fn=…) |
pinchtab_wait(for="function", value=…) |
pinchtab_press(key=…) |
pinchtab_key(action="press", key=…) |
pinchtab_keydown(key=…) |
pinchtab_key(action="down", key=…) |
pinchtab_keyup(key=…) |
pinchtab_key(action="up", key=…) |
pinchtab_keyboard_type(text=…) |
pinchtab_key(action="type", text=…) |
pinchtab_keyboard_inserttext(text=…) |
pinchtab_key(action="insert", text=…) |
pinchtab_record_start(file=…) |
pinchtab_record(action="start", file=…) |
pinchtab_record_stop(file=…) |
pinchtab_record(action="stop", file=…) |
pinchtab_record_status() |
pinchtab_record(action="status") |
Every parameter of the removed tools is carried over unchanged (timeout and state on
selector waits, fps/quality/scale/tabId on recording, nodeId on key presses). The
tool list an agent loads at session start drops from 47 tools to 36.
See also
.github/workflows/release.yml— GitHub Actions workflow.goreleaser.yml— Go binary release confignpm/package.json— npm package metadata