Skip to content

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

chore: rename workflows and improve release pipeline (#329)

luigiagent50ede553e2e9
diff --git a/.github/workflows/branch-naming.yml b/.github/workflows/ci-branch-naming.yml
similarity index 98%
rename from .github/workflows/branch-naming.yml
rename to .github/workflows/ci-branch-naming.yml
index 70776c12..67924344 100644
--- a/.github/workflows/branch-naming.yml
+++ b/.github/workflows/ci-branch-naming.yml
@@ -1,4 +1,4 @@
-name: Branch Naming
+name: CI / Branch Naming
on:
pull_request:
diff --git a/.github/workflows/dashboard.yml b/.github/workflows/ci-dashboard.yml
similarity index 80%
rename from .github/workflows/dashboard.yml
rename to .github/workflows/ci-dashboard.yml
index bbbde3a5..3b28c5ba 100644
--- a/.github/workflows/dashboard.yml
+++ b/.github/workflows/ci-dashboard.yml
@@ -1,4 +1,4 @@
-name: Dashboard
+name: CI / Dashboard
on:
push:
@@ -7,19 +7,17 @@ on:
- 'dashboard/**'
- 'internal/api/types/**'
- 'scripts/build-dashboard.sh'
- - '.github/workflows/dashboard.yml'
+ - '.github/workflows/ci-dashboard.yml'
- '.github/workflows/reusable-dashboard.yml'
pull_request:
paths:
- 'dashboard/**'
- 'internal/api/types/**'
- 'scripts/build-dashboard.sh'
- - '.github/workflows/dashboard.yml'
+ - '.github/workflows/ci-dashboard.yml'
- '.github/workflows/reusable-dashboard.yml'
workflow_dispatch:
-env:
- FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
permissions:
contents: read
diff --git a/.github/workflows/ci-docs.yml b/.github/workflows/ci-docs.yml
new file mode 100644
index 00000000..d03fdf69
--- /dev/null
+++ b/.github/workflows/ci-docs.yml
@@ -0,0 +1,27 @@
+name: CI / Docs
+
+on:
+ push:
+ branches: [main]
+ paths:
+ - 'docs/**'
+ - '.github/workflows/ci-docs.yml'
+ - '.github/workflows/reusable-docs.yml'
+ pull_request:
+ branches: [main]
+ paths:
+ - 'docs/**'
+ - '.github/workflows/ci-docs.yml'
+ - '.github/workflows/reusable-docs.yml'
+ workflow_dispatch:
+
+
+permissions:
+ contents: read
+
+jobs:
+ docs:
+ if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
+ uses: ./.github/workflows/reusable-docs.yml
+ with:
+ ref: ${{ github.sha }}
diff --git a/.github/workflows/e2e.yml b/.github/workflows/ci-e2e.yml
similarity index 81%
rename from .github/workflows/e2e.yml
rename to .github/workflows/ci-e2e.yml
index 5cf5359d..6a1869d7 100644
--- a/.github/workflows/e2e.yml
+++ b/.github/workflows/ci-e2e.yml
@@ -1,4 +1,4 @@
-name: E2E
+name: CI / E2E
permissions:
contents: read
@@ -15,13 +15,11 @@ on:
- 'plugin/**'
workflow_dispatch:
-env:
- FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
jobs:
api-fast:
if: github.event_name != 'workflow_dispatch'
- uses: ./.github/workflows/reusable-e2e-suite.yml
+ uses: ./.github/workflows/reusable-e2e.yml
with:
ref: ${{ github.sha }}
suite: api-fast
@@ -31,7 +29,7 @@ jobs:
cli-fast:
if: github.event_name != 'workflow_dispatch'
- uses: ./.github/workflows/reusable-e2e-suite.yml
+ uses: ./.github/workflows/reusable-e2e.yml
with:
ref: ${{ github.sha }}
suite: cli-fast
@@ -41,7 +39,7 @@ jobs:
full-api:
if: github.event_name == 'workflow_dispatch'
- uses: ./.github/workflows/reusable-e2e-suite.yml
+ uses: ./.github/workflows/reusable-e2e.yml
with:
ref: ${{ github.sha }}
suite: full-api
@@ -51,7 +49,7 @@ jobs:
full-cli:
if: github.event_name == 'workflow_dispatch'
- uses: ./.github/workflows/reusable-e2e-suite.yml
+ uses: ./.github/workflows/reusable-e2e.yml
with:
ref: ${{ github.sha }}
suite: full-cli
diff --git a/.github/workflows/go-verify.yml b/.github/workflows/ci-go.yml
similarity index 80%
rename from .github/workflows/go-verify.yml
rename to .github/workflows/ci-go.yml
index 2a7d0b7e..e17d1d00 100644
--- a/.github/workflows/go-verify.yml
+++ b/.github/workflows/ci-go.yml
@@ -1,4 +1,4 @@
-name: Go Verification
+name: CI / Go
on:
push:
@@ -21,8 +21,6 @@ on:
- 'plugin/**'
workflow_dispatch:
-env:
- FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
permissions:
contents: read
@@ -30,6 +28,6 @@ permissions:
jobs:
go:
if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
- uses: ./.github/workflows/reusable-go-verify.yml
+ uses: ./.github/workflows/reusable-go.yml
with:
ref: ${{ github.sha }}
diff --git a/.github/workflows/ci-npm.yml b/.github/workflows/ci-npm.yml
new file mode 100644
index 00000000..bfa4d8e6
--- /dev/null
+++ b/.github/workflows/ci-npm.yml
@@ -0,0 +1,22 @@
+name: CI / npm
+
+on:
+ pull_request:
+ paths:
+ - 'npm/**'
+ - '.github/workflows/ci-npm.yml'
+ - '.github/workflows/reusable-npm.yml'
+ push:
+ tags:
+ - 'v*'
+ workflow_dispatch:
+
+
+permissions:
+ contents: read
+
+jobs:
+ npm:
+ uses: ./.github/workflows/reusable-npm.yml
+ with:
+ ref: ${{ github.sha }}
diff --git a/.github/workflows/docs-verify.yml b/.github/workflows/docs-verify.yml
deleted file mode 100644
index b863601e..00000000
--- a/.github/workflows/docs-verify.yml
+++ /dev/null
@@ -1,29 +0,0 @@
-name: Documentation Verification
-
-on:
- push:
- branches: [main]
- paths:
- - 'docs/**'
- - '.github/workflows/docs-verify.yml'
- - '.github/workflows/reusable-docs-verify.yml'
- pull_request:
- branches: [main]
- paths:
- - 'docs/**'
- - '.github/workflows/docs-verify.yml'
- - '.github/workflows/reusable-docs-verify.yml'
- workflow_dispatch:
-
-env:
- FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
-
-permissions:
- contents: read
-
-jobs:
- docs:
- if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
- uses: ./.github/workflows/reusable-docs-verify.yml
- with:
- ref: ${{ github.sha }}
diff --git a/.github/workflows/npm-verify.yml b/.github/workflows/npm-verify.yml
deleted file mode 100644
index 90413dc3..00000000
--- a/.github/workflows/npm-verify.yml
+++ /dev/null
@@ -1,29 +0,0 @@
-name: npm Package Verification
-
-on:
- pull_request:
- paths:
- - 'npm/**'
- - '.github/workflows/npm-verify.yml'
- - '.github/workflows/reusable-npm-verify.yml'
- push:
- tags:
- - 'v*'
- workflow_dispatch:
- workflow_call:
- inputs:
- ref:
- required: true
- type: string
-
-env:
- FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
-
-permissions:
- contents: read
-
-jobs:
- npm:
- uses: ./.github/workflows/reusable-npm-verify.yml
- with:
- ref: ${{ inputs.ref || github.sha }}
diff --git a/.github/workflows/release-manual-publish.yml b/.github/workflows/release-manual-publish.yml
new file mode 100644
index 00000000..06982a38
--- /dev/null
+++ b/.github/workflows/release-manual-publish.yml
@@ -0,0 +1,62 @@
+name: Release / Manual Publish
+
+on:
+ workflow_dispatch:
+ inputs:
+ version:
+ description: 'Release version (e.g. 0.8.0, without v prefix)'
+ required: true
+ ref:
+ description: 'Git ref to tag. Defaults to main.'
+ required: false
+ default: 'main'
+
+permissions:
+ contents: write
+
+concurrency:
+ group: release-manual-${{ inputs.version }}
+ 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
+ runs-on: ubuntu-latest
+ environment:
+ name: release-approval
+ permissions:
+ contents: write
+ steps:
+ - uses: actions/checkout@v6
+ with:
+ fetch-depth: 0
+ ref: ${{ needs.validate.outputs.sha }}
+
+ - name: Create and push tag
+ run: |
+ TAG="${{ needs.validate.outputs.tag }}"
+
+ if git ls-remote --exit-code --tags origin "refs/tags/$TAG" >/dev/null 2>&1; then
+ echo "tag $TAG already exists 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"
+
+ - name: Summarize
+ run: |
+ echo "## Release Tag Created (Manual)" >> "$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"
diff --git a/.github/workflows/prepare-release.yml b/.github/workflows/release-prepare.yml
similarity index 59%
rename from .github/workflows/prepare-release.yml
rename to .github/workflows/release-prepare.yml
index c04cdd26..c884b8a9 100644
--- a/.github/workflows/prepare-release.yml
+++ b/.github/workflows/release-prepare.yml
@@ -1,10 +1,10 @@
-name: Prepare Release
+name: Release / Prepare
on:
workflow_dispatch:
inputs:
version:
- description: 'Release version (for example 0.8.0, without v prefix)'
+ description: 'Release version (e.g. 0.8.0, without v prefix)'
required: true
ref:
description: 'Git ref to release. Defaults to main.'
@@ -12,7 +12,6 @@ on:
default: 'main'
env:
- FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
GORELEASER_VERSION: v2.14.3
permissions:
@@ -24,59 +23,14 @@ concurrency:
jobs:
validate:
- name: Validate Release Input
- runs-on: ubuntu-latest
- outputs:
- version: ${{ steps.meta.outputs.version }}
- tag: ${{ steps.meta.outputs.tag }}
- sha: ${{ steps.meta.outputs.sha }}
- ref: ${{ steps.meta.outputs.ref }}
- steps:
- - uses: actions/checkout@v6
- with:
- fetch-depth: 0
- ref: ${{ inputs.ref }}
-
- - name: Validate version and tag target
- id: meta
- run: |
- VERSION="${{ inputs.version }}"
- VERSION="${VERSION#v}"
- if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
- echo "version must look like 0.8.0" >&2
- exit 1
- fi
-
- TAG="v$VERSION"
- if git rev-parse "$TAG" >/dev/null 2>&1; then
- echo "tag $TAG already exists locally" >&2
- exit 1
- 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
- exit 1
- fi
-
- SHA="$(git rev-parse HEAD)"
- {
- echo "version=$VERSION"
- echo "tag=$TAG"
- echo "sha=$SHA"
- echo "ref=${{ inputs.ref }}"
- } >> "$GITHUB_OUTPUT"
-
- - name: Summarize candidate
- run: |
- echo "## Release Candidate" >> "$GITHUB_STEP_SUMMARY"
- echo "- Version: ${{ steps.meta.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
- echo "- Tag: ${{ steps.meta.outputs.tag }}" >> "$GITHUB_STEP_SUMMARY"
- echo "- Ref: ${{ steps.meta.outputs.ref }}" >> "$GITHUB_STEP_SUMMARY"
- echo "- Commit: \`${{ steps.meta.outputs.sha }}\`" >> "$GITHUB_STEP_SUMMARY"
+ uses: ./.github/workflows/reusable-validate-release.yml
+ with:
+ version: ${{ inputs.version }}
+ ref: ${{ inputs.ref }}
go-checks:
needs: validate
- uses: ./.github/workflows/reusable-go-verify.yml
+ uses: ./.github/workflows/reusable-go.yml
with:
ref: ${{ needs.validate.outputs.sha }}
@@ -88,25 +42,34 @@ jobs:
docs-checks:
needs: validate
- uses: ./.github/workflows/reusable-docs-verify.yml
+ uses: ./.github/workflows/reusable-docs.yml
with:
ref: ${{ needs.validate.outputs.sha }}
npm-checks:
needs: validate
- uses: ./.github/workflows/reusable-npm-verify.yml
+ uses: ./.github/workflows/reusable-npm.yml
with:
ref: ${{ needs.validate.outputs.sha }}
version: ${{ needs.validate.outputs.version }}
- e2e-release:
+ e2e-api-full:
needs: validate
- uses: ./.github/workflows/reusable-e2e-suite.yml
+ uses: ./.github/workflows/reusable-e2e.yml
with:
ref: ${{ needs.validate.outputs.sha }}
- suite: release
- summary_title: Release E2E
- timeout_minutes: 45
+ suite: api-full
+ summary_title: Release E2E (API)
+ timeout_minutes: 30
+
+ e2e-cli-full:
+ needs: validate
+ uses: ./.github/workflows/reusable-e2e.yml
+ with:
+ ref: ${{ needs.validate.outputs.sha }}
+ suite: cli-full
+ summary_title: Release E2E (CLI)
+ timeout_minutes: 30
docker-smoke:
needs: validate
@@ -174,16 +137,44 @@ jobs:
- dashboard-checks
- docs-checks
- npm-checks
- - e2e-release
+ - e2e-api-full
+ - e2e-cli-full
- docker-smoke
- publish-dry-run
+ if: >-
+ always() && !cancelled()
+ && needs.validate.result == 'success'
+ && needs.go-checks.result == 'success'
+ && needs.dashboard-checks.result == 'success'
+ && needs.docs-checks.result == 'success'
+ && needs.npm-checks.result == 'success'
+ && needs.publish-dry-run.result == 'success'
runs-on: ubuntu-latest
environment:
name: release-approval
steps:
- - name: Await approval
+ - name: Report check results
run: |
- echo "Approved release candidate ${{ needs.validate.outputs.tag }} at ${{ needs.validate.outputs.sha }}"
+ echo "## Pre-Release Check Results" >> "$GITHUB_STEP_SUMMARY"
+ echo "" >> "$GITHUB_STEP_SUMMARY"
+ echo "| Check | Status |" >> "$GITHUB_STEP_SUMMARY"
+ echo "|-------|--------|" >> "$GITHUB_STEP_SUMMARY"
+ echo "| Go | ✅ |" >> "$GITHUB_STEP_SUMMARY"
+ echo "| Dashboard | ✅ |" >> "$GITHUB_STEP_SUMMARY"
+ echo "| Docs | ✅ |" >> "$GITHUB_STEP_SUMMARY"
+ echo "| npm | ✅ |" >> "$GITHUB_STEP_SUMMARY"
+ echo "| Publish dry run | ✅ |" >> "$GITHUB_STEP_SUMMARY"
+ echo "| Docker smoke | ${{ needs.docker-smoke.result == 'success' && '✅' || '⚠️ ' }}${{ needs.docker-smoke.result }} |" >> "$GITHUB_STEP_SUMMARY"
+ echo "| E2E API | ${{ needs.e2e-api-full.result == 'success' && '✅' || '⚠️ ' }}${{ needs.e2e-api-full.result }} |" >> "$GITHUB_STEP_SUMMARY"
+ echo "| E2E CLI | ${{ needs.e2e-cli-full.result == 'success' && '✅' || '⚠️ ' }}${{ needs.e2e-cli-full.result }} |" >> "$GITHUB_STEP_SUMMARY"
+ echo "" >> "$GITHUB_STEP_SUMMARY"
+
+ if [ "${{ needs.e2e-api-full.result }}" != "success" ] || [ "${{ needs.e2e-cli-full.result }}" != "success" ] || [ "${{ needs.docker-smoke.result }}" != "success" ]; then
+ echo "⚠️ **Some checks failed — review artifacts before approving.**" >> "$GITHUB_STEP_SUMMARY"
+ fi
+
+ echo "" >> "$GITHUB_STEP_SUMMARY"
+ echo "Release candidate: **${{ needs.validate.outputs.tag }}** at \`${{ needs.validate.outputs.sha }}\`" >> "$GITHUB_STEP_SUMMARY"
create-tag:
name: Create Release Tag
diff --git a/.github/workflows/release.yml b/.github/workflows/release-publish.yml
similarity index 92%
rename from .github/workflows/release.yml
rename to .github/workflows/release-publish.yml
index e179189e..8e691f99 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release-publish.yml
@@ -1,11 +1,10 @@
-name: Release
+name: Release / Publish
on:
push:
tags: ['v*']
env:
- FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
GORELEASER_VERSION: v2.14.3
permissions:
@@ -117,21 +116,21 @@ jobs:
echo "tag=$TAG" >> "$GITHUB_OUTPUT"
echo "version=$VERSION" >> "$GITHUB_OUTPUT"
- - uses: docker/setup-qemu-action@v3
- - uses: docker/setup-buildx-action@v3
+ - uses: docker/setup-qemu-action@v4
+ - uses: docker/setup-buildx-action@v4
- - uses: docker/login-action@v3
+ - uses: docker/login-action@v4
with:
username: ${{ secrets.DOCKERHUB_USER }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- - uses: docker/login-action@v3
+ - uses: docker/login-action@v4
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
- - uses: docker/build-push-action@v6
+ - uses: docker/build-push-action@v7
with:
context: .
file: ./Dockerfile
@@ -154,7 +153,7 @@ jobs:
needs:
- release
- npm
- uses: ./.github/workflows/publish-skill.yml
+ uses: ./.github/workflows/reusable-publish-skill.yml
with:
version: ${{ github.ref_name }}
secrets:
diff --git a/.github/workflows/reusable-dashboard.yml b/.github/workflows/reusable-dashboard.yml
index 580d9b3e..2a1841da 100644
--- a/.github/workflows/reusable-dashboard.yml
+++ b/.github/workflows/reusable-dashboard.yml
@@ -1,4 +1,4 @@
-name: Reusable Dashboard Checks
+name: Reusable / Dashboard
on:
workflow_call:
@@ -7,8 +7,6 @@ on:
required: true
type: string
-env:
- FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
permissions:
contents: read
diff --git a/.github/workflows/reusable-docker-smoke.yml b/.github/workflows/reusable-docker-smoke.yml
index 347f90e7..a58c7d8b 100644
--- a/.github/workflows/reusable-docker-smoke.yml
+++ b/.github/workflows/reusable-docker-smoke.yml
@@ -1,4 +1,4 @@
-name: Reusable Docker Smoke Test
+name: Reusable / Docker Smoke
on:
workflow_call:
@@ -7,8 +7,6 @@ on:
required: true
type: string
-env:
- FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
permissions:
contents: read
diff --git a/.github/workflows/reusable-docs-verify.yml b/.github/workflows/reusable-docs.yml
similarity index 83%
rename from .github/workflows/reusable-docs-verify.yml
rename to .github/workflows/reusable-docs.yml
index 5736ef81..06ee733f 100644
--- a/.github/workflows/reusable-docs-verify.yml
+++ b/.github/workflows/reusable-docs.yml
@@ -1,4 +1,4 @@
-name: Reusable Documentation Verification
+name: Reusable / Docs
on:
workflow_call:
@@ -7,8 +7,6 @@ on:
required: true
type: string
-env:
- FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
permissions:
contents: read
diff --git a/.github/workflows/reusable-e2e-suite.yml b/.github/workflows/reusable-e2e.yml
similarity index 97%
rename from .github/workflows/reusable-e2e-suite.yml
rename to .github/workflows/reusable-e2e.yml
index 918178bf..d34c23d7 100644
--- a/.github/workflows/reusable-e2e-suite.yml
+++ b/.github/workflows/reusable-e2e.yml
@@ -1,4 +1,4 @@
-name: Reusable E2E Suite
+name: Reusable / E2E
on:
workflow_call:
@@ -24,8 +24,6 @@ on:
type: boolean
default: false
-env:
- FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
permissions:
contents: read
@@ -48,7 +46,7 @@ jobs:
cache: true
- name: Set up Docker Buildx
- uses: docker/setup-buildx-action@v3
+ uses: docker/setup-buildx-action@v4
- name: Run E2E suite
id: e2e
diff --git a/.github/workflows/reusable-go-verify.yml b/.github/workflows/reusable-go.yml
similarity index 97%
rename from .github/workflows/reusable-go-verify.yml
rename to .github/workflows/reusable-go.yml
index 172c47de..c635dffb 100644
--- a/.github/workflows/reusable-go-verify.yml
+++ b/.github/workflows/reusable-go.yml
@@ -1,4 +1,4 @@
-name: Reusable Go Verification
+name: Reusable / Go
on:
workflow_call:
@@ -7,8 +7,6 @@ on:
required: true
type: string
-env:
- FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
permissions:
contents: read
diff --git a/.github/workflows/reusable-npm-verify.yml b/.github/workflows/reusable-npm.yml
similarity index 89%
rename from .github/workflows/reusable-npm-verify.yml
rename to .github/workflows/reusable-npm.yml
index 8f64052f..f5063500 100644
--- a/.github/workflows/reusable-npm-verify.yml
+++ b/.github/workflows/reusable-npm.yml
@@ -1,4 +1,4 @@
-name: Reusable npm Package Verification
+name: Reusable / npm
on:
workflow_call:
@@ -10,8 +10,6 @@ on:
required: false
type: string
-env:
- FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
permissions:
contents: read
diff --git a/.github/workflows/publish-skill.yml b/.github/workflows/reusable-publish-skill.yml
similarity index 95%
rename from .github/workflows/publish-skill.yml
rename to .github/workflows/reusable-publish-skill.yml
index 711c034f..7c23e520 100644
--- a/.github/workflows/publish-skill.yml
+++ b/.github/workflows/reusable-publish-skill.yml
@@ -1,4 +1,4 @@
-name: Publish Skill
+name: Reusable / Publish Skill
on:
workflow_call:
@@ -15,8 +15,6 @@ on:
description: 'Skill version (e.g. 0.2.0, without v prefix)'
required: true
-env:
- FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
permissions:
contents: read
diff --git a/.github/workflows/reusable-validate-release.yml b/.github/workflows/reusable-validate-release.yml
new file mode 100644
index 00000000..2e09306d
--- /dev/null
+++ b/.github/workflows/reusable-validate-release.yml
@@ -0,0 +1,82 @@
+name: Reusable / Validate Release
+
+on:
+ workflow_call:
+ inputs:
+ version:
+ description: 'Release version (e.g. 0.8.0, without v prefix)'
+ required: true
+ type: string
+ ref:
+ description: 'Git ref to release. Defaults to main.'
+ required: false
+ type: string
+ default: 'main'
+ outputs:
+ version:
+ description: 'Validated version (without v prefix)'
+ value: ${{ jobs.validate.outputs.version }}
+ tag:
+ description: 'Release tag (v-prefixed)'
+ value: ${{ jobs.validate.outputs.tag }}
+ sha:
+ description: 'Resolved commit SHA'
+ value: ${{ jobs.validate.outputs.sha }}
+ ref:
+ description: 'Git ref used'
+ value: ${{ jobs.validate.outputs.ref }}
+
+permissions:
+ contents: read
+
+jobs:
+ validate:
+ name: Validate Release Input
+ runs-on: ubuntu-latest
+ outputs:
+ version: ${{ steps.meta.outputs.version }}
+ tag: ${{ steps.meta.outputs.tag }}
+ sha: ${{ steps.meta.outputs.sha }}
+ ref: ${{ steps.meta.outputs.ref }}
+ steps:
+ - uses: actions/checkout@v6
+ with:
+ fetch-depth: 0
+ ref: ${{ inputs.ref }}
+
+ - name: Validate version and tag target
+ id: meta
+ run: |
+ VERSION="${{ inputs.version }}"
+ VERSION="${VERSION#v}"
+ if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+ echo "version must look like 0.8.0" >&2
+ exit 1
+ fi
+
+ TAG="v$VERSION"
+ if git rev-parse "$TAG" >/dev/null 2>&1; then
+ echo "tag $TAG already exists locally" >&2
+ exit 1
+ 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
+ exit 1
+ fi
+
+ SHA="$(git rev-parse HEAD)"
+ {
+ echo "version=$VERSION"
+ echo "tag=$TAG"
+ echo "sha=$SHA"
+ echo "ref=${{ inputs.ref }}"
+ } >> "$GITHUB_OUTPUT"
+
+ - name: Summarize candidate
+ run: |
+ echo "## Release Candidate" >> "$GITHUB_STEP_SUMMARY"
+ echo "- Version: ${{ steps.meta.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
+ echo "- Tag: ${{ steps.meta.outputs.tag }}" >> "$GITHUB_STEP_SUMMARY"
+ echo "- Ref: ${{ steps.meta.outputs.ref }}" >> "$GITHUB_STEP_SUMMARY"
+ echo "- Commit: \`${{ steps.meta.outputs.sha }}\`" >> "$GITHUB_STEP_SUMMARY"
diff --git a/docs/guides/contributing.md b/docs/guides/contributing.md
index 60f4f834..58d7d794 100644
--- a/docs/guides/contributing.md
+++ b/docs/guides/contributing.md
@@ -342,14 +342,38 @@ git push origin feat/my-feature
## Continuous Integration
-GitHub Actions automatically runs on push:
-- Format checks (gofmt)
-- Vet checks (go vet)
-- Build verification
-- Full test suite with coverage
-- Linting (golangci-lint)
-
-See `.github/workflows/` for details.
+Workflows follow a naming convention:
+
+| Prefix | Purpose | Example |
+|--------|---------|---------|
+| `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** |
+
+### CI Checks
+
+Run automatically on pull requests and/or push to `main`:
+
+| Workflow | Triggers | What it checks |
+|----------|----------|----------------|
+| **CI / Go** | PR + push | gofmt, vet, build, tests, coverage, lint, security |
+| **CI / Dashboard** | PR + push (dashboard paths) | TypeScript, ESLint, Prettier, tests, build |
+| **CI / Docs** | PR + push (docs paths) | docs.json reference validation |
+| **CI / npm** | PR (npm paths) + tag push | npm package verification |
+| **CI / E2E** | PR (fast suites) + manual (full suites) | Docker-based end-to-end tests |
+| **CI / Branch Naming** | PR | Branch name convention enforcement |
+
+### Release Pipeline
+
+| 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 |
+
+In **Release / Prepare**, 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.
---