docs/ci.md

metadata

title: CI Pipeline
description: How the OpenClaw CI pipeline works
summary: CI job graph, scope gates, and local command equivalents
read_when:
  - You need to understand why a CI job did or did not run
  - You are debugging failing GitHub Actions checks

CI Pipeline

The CI runs on every push to main and every pull request. It uses smart scoping to skip expensive jobs when only unrelated areas changed.

Job Overview

Job	Purpose	When it runs
docs-scope	Detect docs-only changes	Always
changed-scope	Detect which areas changed (node/macos/android/windows)	Non-doc changes
check	TypeScript types, lint, format	Non-docs, node changes
check-docs	Markdown lint + broken link check	Docs changed
secrets	Detect leaked secrets	Always
build-artifacts	Build dist once, share with release-check	Pushes to main, node changes
release-check	Validate npm pack contents	Pushes to main after build
checks	Node tests + protocol check on PRs; Bun compat on push	Non-docs, node changes
compat-node22	Minimum supported Node runtime compatibility	Pushes to main, node changes
checks-windows	Windows-specific tests	Non-docs, windows-relevant changes
macos	Swift lint/build/test + TS tests	PRs with macos changes
android	Gradle build + tests	Non-docs, android changes

Fail-Fast Order

Jobs are ordered so cheap checks fail before expensive ones run:

1. docs-scope + changed-scope + check + secrets (parallel, cheap gates first)
2. PRs: checks (Linux Node test split into 2 shards), checks-windows, macos, android
3. Pushes to main: build-artifacts + release-check + Bun compat + compat-node22

Scope logic lives in scripts/ci-changed-scope.mjs and is covered by unit tests in src/scripts/ci-changed-scope.test.ts.

Runners

Runner	Jobs
blacksmith-16vcpu-ubuntu-2404	Most Linux jobs, including scope detection
blacksmith-32vcpu-windows-2025	checks-windows
macos-latest	macos, ios

Local Equivalents

pnpm check          # types + lint + format
pnpm test           # vitest tests
pnpm check:docs     # docs format + lint + broken links
pnpm release:check  # validate npm pack