openclaw/docs/reference/pipeline.md

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

# After hotfix merges to main
git checkout develop && git cherry-pick <commit-sha> && git push
git checkout alpha && git cherry-pick <commit-sha> && git push
git checkout beta && git cherry-pick <commit-sha> && git push

npm Installation by Channel

# 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:

# 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)

Setup

Required Secrets

Configure these in GitHub repo Settings → Secrets and variables → Actions:

Secret	Required?	Purpose	How to get it
GITHUB_TOKEN	Automatic	PR creation, Docker registry, branch ops	Provided by GitHub Actions — no setup needed
NPM_TOKEN	Yes (for publishing)	npm publish with @alpha, @beta, @latest tags	npmjs.com → Access Tokens → Generate New Token → Automation
DISCORD_WEBHOOK_URL	Optional	Notifications for promotions, test results, deployments	Discord → Server Settings → Integrations → Webhooks

Without NPM_TOKEN, the pipeline runs normally but skips npm publishing. Without DISCORD_WEBHOOK_URL, notifications are silently skipped.

Branch Setup

Staging branches are auto-created from main when the first promotion runs. No manual setup required.

Rollback

The rollback workflow (Actions → Rollback) re-tags npm and Docker to a previous version. Requires NPM_TOKEN and is manual-trigger only.