From 45789653c03f70b317e84840006861428f48a844 Mon Sep 17 00:00:00 2001 From: quotentiroler Date: Fri, 6 Feb 2026 15:35:39 -0800 Subject: [PATCH] feat(ci): add hotfix workflow and pipeline documentation --- .github/workflows/hotfix-pr.yml | 91 ++++++++++++++++++++ docs/reference/pipeline.md | 144 ++++++++++++++++++++++++++++++++ 2 files changed, 235 insertions(+) create mode 100644 .github/workflows/hotfix-pr.yml create mode 100644 docs/reference/pipeline.md diff --git a/.github/workflows/hotfix-pr.yml b/.github/workflows/hotfix-pr.yml new file mode 100644 index 0000000000..0275258b01 --- /dev/null +++ b/.github/workflows/hotfix-pr.yml @@ -0,0 +1,91 @@ +name: Hotfix PR + +# Emergency hotfix workflow - bypasses staging pipeline +# Use for critical security fixes or production-breaking bugs only +# +# Flow: hotfix/* → main (directly, with expedited review) + +on: + push: + branches: + - 'hotfix/**' + +permissions: + contents: read + pull-requests: write + +jobs: + create-pr: + name: Create Hotfix PR + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Check for existing PR + id: check-pr + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + BRANCH="${{ github.ref_name }}" + + EXISTING=$(gh pr list --head "$BRANCH" --base main --json number --jq '.[0].number // empty') + + if [ -n "$EXISTING" ]; then + echo "exists=true" >> $GITHUB_OUTPUT + echo "pr_number=$EXISTING" >> $GITHUB_OUTPUT + echo "Hotfix PR #$EXISTING already exists" + else + echo "exists=false" >> $GITHUB_OUTPUT + fi + + - name: Create Hotfix PR + if: steps.check-pr.outputs.exists != 'true' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + BRANCH="${{ github.ref_name }}" + + # Extract title from branch name + TITLE=$(echo "$BRANCH" | sed 's|^hotfix/||; s|-| |g; s|_| |g') + TITLE="🚨 HOTFIX: $(echo "${TITLE:0:1}" | tr '[:lower:]' '[:upper:]')${TITLE:1}" + + gh pr create \ + --base main \ + --head "$BRANCH" \ + --title "$TITLE" \ + --label "hotfix,priority:critical" \ + --body "## 🚨 Emergency Hotfix + +**This PR bypasses the normal staging pipeline.** + +### What's broken? + + +### Root cause + + +### Fix + + +### Verification +- [ ] Tested locally +- [ ] Reviewed by at least one other maintainer +- [ ] Post-merge monitoring plan in place + +--- +⚠️ **After merging:** Cherry-pick this fix to \`develop\`, \`alpha\`, and \`beta\` branches to keep them in sync. + +*This PR was auto-created by the hotfix-pr workflow.*" + + echo "Created hotfix PR: $BRANCH → main" + + - name: Add urgent label + if: steps.check-pr.outputs.exists != 'true' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + # Labels may not exist, so ignore errors + gh pr edit "${{ github.ref_name }}" --add-label "hotfix" 2>/dev/null || true diff --git a/docs/reference/pipeline.md b/docs/reference/pipeline.md new file mode 100644 index 0000000000..d0a32b0f62 --- /dev/null +++ b/docs/reference/pipeline.md @@ -0,0 +1,144 @@ +# Release Pipeline + +This document describes openclaw's staged release pipeline for contributors and maintainers. + +## Branch Strategy + +``` +dev/* ──────► develop ──────► alpha ──────► beta ──────► main +feature/* │ │ │ │ +fix/* │ │ │ │ + ▼ ▼ ▼ ▼ + Internal Alpha Beta Stable + testing testers testers release +``` + +### Branch Purposes + +| Branch | Purpose | npm tag | Who uses it | +|--------|---------|---------|-------------| +| `dev/*`, `feature/*`, `fix/*` | Active development | - | Contributors | +| `develop` | Integration branch | - | CI validation | +| `alpha` | Early testing | `@alpha` | Internal testers | +| `beta` | Pre-release testing | `@beta` | Beta testers | +| `main` | Production releases | `@latest` | Everyone | + +## Workflow Overview + +### 1. Feature Development + +1. Create a branch: `git checkout -b dev/my-feature` +2. Make changes and push +3. **Auto-PR created** to `develop` via `feature-pr.yml` +4. Get review, iterate, merge to `develop` + +### 2. Promotion Through Stages + +When code lands in `develop`, the `promote-branch.yml` workflow: + +1. Runs tests appropriate for that stage +2. Creates a PR to the next branch (develop → alpha → beta → main) +3. Auto-merges `develop → alpha` if tests pass +4. Requires manual approval for `alpha → beta` and `beta → main` + +### 3. Releases + +Releases are triggered manually via the **Release** workflow: + +1. Go to Actions → Release → Run workflow +2. Select release type: `alpha`, `beta`, or `stable` +3. Workflow runs: version bump → changelog → tests → npm publish → Docker push + +## Test Coverage by Stage + +| Stage | Tests Run | +|-------|-----------| +| develop | tsgo, lint, format, protocol, unit tests (Node + Bun) | +| alpha | + secrets scan | +| beta | + Windows tests | +| stable | + macOS tests, install smoke tests | + +## Emergency Hotfixes + +For critical production issues: + +1. Create branch: `git checkout -b hotfix/critical-bug` +2. Push → **Auto-PR created** directly to `main` +3. Get expedited review (skip staging) +4. After merge, cherry-pick to `develop`, `alpha`, `beta` to sync + +```bash +# After hotfix merges to main +git checkout develop && git cherry-pick && git push +git checkout alpha && git cherry-pick && git push +git checkout beta && git cherry-pick && git push +``` + +## npm Installation by Channel + +```bash +# Stable (default) +npm install -g openclaw + +# Beta testing +npm install -g openclaw@beta + +# Alpha testing (bleeding edge) +npm install -g openclaw@alpha +``` + +## Docker Images + +Images are published to GitHub Container Registry: + +```bash +# Stable +docker pull ghcr.io/openclaw/openclaw:latest + +# Beta +docker pull ghcr.io/openclaw/openclaw:beta + +# Specific version +docker pull ghcr.io/openclaw/openclaw:2026.2.6 +``` + +## Version Format + +- **Stable**: `YYYY.M.D` (e.g., `2026.2.6`) +- **Beta**: `YYYY.M.D-beta.N` (e.g., `2026.2.6-beta.1`) +- **Alpha**: `YYYY.M.D-alpha.N` (e.g., `2026.2.6-alpha.3`) + +## Maintainer Setup + +After merging this pipeline to `main`, create the staging branches: + +```bash +git checkout main && git pull +git branch develop && git push origin develop +git branch alpha && git push origin alpha +git branch beta && git push origin beta +``` + +### Recommended Branch Protection (GitHub Settings) + +| Branch | Required reviews | Status checks | Force push | +|--------|-----------------|---------------|------------| +| `main` | 1 | All CI | ❌ | +| `beta` | 1 | All CI | ❌ | +| `alpha` | 0 | Core CI | ❌ | +| `develop` | 0 | Core CI | ❌ | + +## Workflow Files + +| Workflow | Purpose | +|----------|---------| +| `ci.yml` | Core CI (lint, test, build) | +| `feature-pr.yml` | Auto-PR from dev/* to develop | +| `hotfix-pr.yml` | Auto-PR from hotfix/* to main | +| `promote-branch.yml` | Stage promotion PRs | +| `testing-strategy.yml` | Stage-specific test suites | +| `deployment-strategy.yml` | npm + Docker publishing | +| `release-orchestrator.yml` | Full release coordination | +| `release.yml` | Manual release trigger | +| `version-operations.yml` | Version bumping | +| `generate-changelog.yml` | Changelog generation |