Skip to content

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

ci: add npm publish to release pipeline

Marioede78d676f00
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 94884d6a..f5c947cb 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,5 +1,22 @@
name: Release
+# Automatic release pipeline triggered on tag push (v0.7.0, etc.)
+#
+# Pipeline:
+# 1. Checkout tag
+# 2. Build Go binary + create GitHub release (goreleaser)
+# 3. Publish npm package (with postinstall binary download support)
+# 4. Build & push Docker images
+#
+# Secrets required:
+# - NPM_TOKEN: npm authentication (https://docs.npmjs.com/creating-and-viewing-access-tokens)
+# - DOCKERHUB_USER / DOCKERHUB_TOKEN: Docker Hub credentials
+# - GITHUB_TOKEN: Automatic (GitHub Actions)
+#
+# To create a release:
+# git tag v0.7.0
+# git push origin v0.7.0
+
on:
push:
tags: ['v*']
@@ -41,6 +58,44 @@ jobs:
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ npm:
+ name: Publish to npm
+ runs-on: ubuntu-latest
+ needs: release
+ permissions:
+ contents: read
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ ref: ${{ github.event.inputs.tag || github.ref }}
+
+ - uses: actions/setup-node@v4
+ with:
+ node-version: '22'
+ registry-url: 'https://registry.npmjs.org'
+
+ - name: Extract version
+ id: version
+ run: |
+ TAG="${{ github.event.inputs.tag || github.ref_name }}"
+ VERSION=${TAG#v} # Remove 'v' prefix
+ echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+
+ - name: Update npm package version
+ working-directory: npm
+ run: |
+ npm version ${{ steps.version.outputs.version }} --no-git-tag-version
+
+ - name: Build TypeScript
+ working-directory: npm
+ run: npm run build
+
+ - name: Publish to npm
+ working-directory: npm
+ run: npm publish
+ env:
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
docker:
name: Docker Image
runs-on: ubuntu-latest
diff --git a/RELEASE.md b/RELEASE.md
new file mode 100644
index 00000000..e347ca41
--- /dev/null
+++ b/RELEASE.md
@@ -0,0 +1,158 @@
+# Release Process
+
+Pinchtab uses an automated CI/CD pipeline triggered by Git tags. When you push a tag like `v0.7.0`, GitHub Actions:
+
+1. **Builds Go binaries** — darwin-arm64, darwin-x64, linux-x64, linux-arm64, windows-x64
+2. **Creates GitHub release** — with checksums.txt for integrity verification
+3. **Publishes to npm** — TypeScript SDK with auto-download postinstall script
+4. **Builds Docker images** — linux/amd64, linux/arm64
+
+## 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
+
+### Local setup
+
+```bash
+# 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 package.json | jq .version # npm package
+cat go.mod | grep "module" # Go module
+git describe --tags # latest tag
+```
+
+## Releasing
+
+### For patch/minor versions (recommended)
+
+```bash
+# 1. Bump version in all places
+npm version patch # or minor, major
+git push origin main
+
+# 2. Create tag
+git tag v0.7.1
+git push origin v0.7.1
+```
+
+### For manual releases
+
+```bash
+# 1. Tag directly
+git tag -a v0.7.1 -m "Release v0.7.1"
+git push origin v0.7.1
+
+# 2. Or via GitHub UI: Releases → Create from tag
+# (workflow will auto-create if not present)
+```
+
+### Using workflow_dispatch (manual trigger)
+
+If you need to re-release an existing tag:
+
+1. Go to **Actions → Release**
+2. **Run workflow**
+3. Enter tag (e.g. `v0.7.1`)
+
+## Pipeline details
+
+### 1. Goreleaser (Go binary)
+
+Triggered on `v*` tag push. Builds binaries and creates GitHub release.
+
+**What it does:**
+- Compiles for all platforms
+- Generates `checksums.txt` (SHA256)
+- Uploads to GitHub Releases
+
+**Configured in:** `.goreleaser.yml`
+
+### 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
+- Postinstall script will download binaries from GitHub Releases
+
+**Key point:** Users who `npm install pinchtab` will:
+```bash
+1. Download npm package
+2. Run postinstall script
+3. Postinstall fetches binary from GitHub releases
+4. Verifies checksum (SHA256)
+5. Makes executable
+```
+
+### 3. Docker
+
+Independent job. Pushes to Docker Hub if configured.
+
+## Troubleshooting
+
+### npm publish fails (403)
+
+- Check **NPM_TOKEN** is set in secrets
+- Verify token has `automation` scope
+- Check you're not already published (can't overwrite existing version)
+
+### Binary checksum mismatch
+
+- goreleaser must generate `checksums.txt`
+- Verify `.goreleaser.yml` has `checksum:` 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:
+
+```bash
+# 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
+
+## See also
+
+- `.github/workflows/release.yml` — GitHub Actions workflow
+- `.goreleaser.yml` — Go binary release config
+- `npm/package.json` — npm package metadata