<!-- source: https://deepwiki.com/openclaw/openclaw/8.2-cicd-pipeline -->

# CI/CD Pipeline

- .agents/skills/crabbox/SKILL.md
- .agents/skills/openclaw-testing/SKILL.md
- .crabbox.yaml
- .github/actionlint.yaml
- .github/actions/ensure-base-commit/action.yml
- .github/actions/setup-node-env/action.yml
- .github/actions/setup-pnpm-store-cache/action.yml
- .github/actions/setup-pnpm-store-cache/ensure-node.sh
- .github/workflows/ci-build-artifacts-testbox.yml
- .github/workflows/ci-check-testbox.yml
- .github/workflows/ci.yml
- .github/workflows/codeql-macos-critical-security.yml
- .github/workflows/crabbox-hydrate.yml
- .github/workflows/openclaw-cross-os-release-checks-reusable.yml
- .github/workflows/website-installer-sync.yml
- .github/workflows/windows-blacksmith-testbox.yml
- AGENTS.md
- CONTRIBUTING.md
- apps/swabble/.github/workflows/ci.yml
- docs/ci.md
- docs/reference/full-release-validation.md
- extensions/msteams/npm-shrinkwrap.json
- extensions/zalouser/npm-shrinkwrap.json
- qa/scenarios/memory/thread-memory-isolation.md
- scripts/AGENTS.md
- scripts/changed-lanes.mjs
- scripts/check-changed.mjs
- scripts/ci-changed-scope.mjs
- scripts/ci-run-timings.mjs
- scripts/crabbox-wrapper.mjs
- scripts/generate-npm-shrinkwrap.mjs
- scripts/lib/ci-node-test-plan.mjs
- scripts/lib/docker-build.sh
- scripts/lib/format-generated-module.mjs
- scripts/openclaw-cross-os-release-checks.ts
- scripts/plugin-npm-publish.sh
- scripts/qa-lab-up.ts
- scripts/run-with-env.mjs
- scripts/test-projects-imports.mjs
- scripts/test-projects-max.mjs
- src/agents/tools/image-tool.providers.live.test.ts
- src/infra/vitest-config.test.ts
- src/scripts/ci-changed-scope.test.ts
- test/package-manager-config.test.ts
- test/package-scripts.test.ts
- test/scripts/changed-lanes.test.ts
- test/scripts/ci-node-test-plan.test.ts
- test/scripts/ci-run-timings.test.ts
- test/scripts/ci-workflow-guards.test.ts
- test/scripts/crabbox-wrapper.test.ts
- test/scripts/format-generated-module.test.ts
- test/scripts/generate-npm-shrinkwrap.test.ts
- test/scripts/openclaw-cross-os-release-checks.test.ts
- test/scripts/openclaw-cross-os-release-workflow.test.ts
- test/scripts/package-acceptance-workflow.test.ts
- test/scripts/qa-lab-up.test.ts
- test/scripts/run-with-env.test.ts
- test/scripts/setup-pnpm-store-cache-ensure-node.test.ts
- test/scripts/website-installer-sync-workflow.test.ts
- test/vitest/vitest.unit-support.config.ts

## Purpose and Scope

This document describes the OpenClaw continuous integration and deployment infrastructure, detailing its GitHub Actions workflows, the intelligent scope detection mechanism used to optimize job execution, test sharding strategies, platform-specific validation processes, and release automation. The CI/CD pipeline is designed to maintain high quality across Node.js, Android, iOS, and macOS components while minimizing build times through aggressive conditional execution and test parallelism.

**Sources:** [.github/workflows/ci.yml1-12](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/ci.yml#L1-L12)

## Overview

The OpenClaw CI pipeline is triggered on every push to the `main` branch and on every pull request [.github/workflows/ci.yml3-25](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/ci.yml#L3-L25) It incorporates a multi-stage execution model, where lightweight "preflight" jobs identify whether subsequent resource-intensive platform-specific jobs should run.

The main workflows include:

- CI ( ci.yml ) : The primary validation workflow running linting, tests, builds, and platform-specific tests .github/workflows/ci.yml 1-58
- Full Release Validation ( full-release-validation.yml ) : An umbrella workflow that orchestrates exhaustive cross-OS and live-provider checks for release candidates test/scripts/package-acceptance-workflow.test.ts 13
- OpenClaw Live And E2E Checks ( openclaw-live-and-e2e-checks-reusable.yml ) : A reusable workflow for running Docker-based end-to-end turns and live model provider coverage test/scripts/package-acceptance-workflow.test.ts 6
- Crabbox Hydrate ( crabbox-hydrate.yml ) : Prepares remote "testbox" environments for heavy validation across Linux, macOS, and Windows .github/workflows/crabbox-hydrate.yml 1-30

**Sources:** [.github/workflows/ci.yml1-58](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/ci.yml#L1-L58) [test/scripts/package-acceptance-workflow.test.ts5-23](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/package-acceptance-workflow.test.ts#L5-L23) [.github/workflows/crabbox-hydrate.yml1-30](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/crabbox-hydrate.yml#L1-L30)

## Scope Detection System

To conserve CI resources and reduce turnaround times, OpenClaw implements a multi-phase detection system. It distinguishes documentation-only changes from code changes and further determines which parts of the system are affected.

### Scope Analysis Data Flow

```

```

### Phase 1: Preflight and Docs-Scope

The `preflight` job runs the `detect-docs-changes` action to analyze the list of changed files [.github/workflows/ci.yml135-139](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/ci.yml#L135-L139) If **only** documentation files changed, it sets `docs_only` to `true`, allowing the pipeline to bypass heavy platform tests [.github/workflows/ci.yml47-138](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/ci.yml#L47-L138)

### Phase 2: Area and Extension Detection

When non-doc changes exist, the pipeline runs `scripts/ci-changed-scope.mjs` to inspect the git diff and set boolean flags for different platform lanes [.github/workflows/ci.yml140-143](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/ci.yml#L140-L143)

- Node Scope : Triggered by changes in src/ , test/ , extensions/ , or core config files .github/workflows/ci.yml 49
- Native Scopes : run_macos and run_android are triggered by changes in apps/macos/ , apps/android/ , and apps/shared/ .github/workflows/ci.yml 50-51
- Plugin/Channel Contracts : Detects if specific integration contracts need re-validation based on changed files in extensions/ .github/workflows/ci.yml 59-61

**Sources:** [.github/workflows/ci.yml37-77](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/ci.yml#L37-L77) [scripts/ci-changed-scope.mjs1-50](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/ci-changed-scope.mjs#L1-L50)

## Test Sharding and Validation Strategies

OpenClaw employs aggressive sharding and specialized validation scripts to maintain high coverage across a complex multi-platform codebase.

### Test Sharding and Matrix Execution

The CI pipeline shards tests to maximize parallelism:

- checks-fast-core : Shards fast Linux correctness lanes, including bundled, protocol, and CI-routing checks .github/workflows/ci.yml 56-58 docs/ci.md 21
- checks-node-core-nondist : Executes core Node.js tests that do not depend on built artifacts, sharded for speed .github/workflows/ci.yml 63-64
- checks-windows : Specifically targets Windows-specific process and path logic, using a matrix for different Windows versions .github/workflows/ci.yml 70-71

### Cross-OS Release Checks

The script `scripts/openclaw-cross-os-release-checks.ts` orchestrates complex "smoke" tests that simulate real-world installation and upgrades across Ubuntu, Windows, and macOS [scripts/openclaw-cross-os-release-checks.ts33-40](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/openclaw-cross-os-release-checks.ts#L33-L40)

**Sources:** [scripts/openclaw-cross-os-release-checks.ts31-40](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/openclaw-cross-os-release-checks.ts#L31-L40) [test/scripts/openclaw-cross-os-release-checks.test.ts140-145](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/openclaw-cross-os-release-checks.test.ts#L140-L145)

## Dependency Audit & Quality Gates

### Knip Dependency Audit

The CI pipeline utilizes **Knip** via the `check-dependencies` job to identify unused files, dependencies, and exports, ensuring the production bundle remains lean [docs/ci.md19](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/ci.md?plain=1#L19-L19)

### CodeQL & Zizmor

- CodeQL : Performs deep static analysis to identify security vulnerabilities and critical logic errors.
- Zizmor : Audits GitHub Actions workflows for insecure patterns such as command injection in run steps docs/ci.md 18

### Package Acceptance

The `package-acceptance.yml` workflow validates that published npm packages are functional. It checks for correctly selected `pnpm` versions from `packageManager` in `package.json` and ensures toolchain compatibility [test/scripts/package-acceptance-workflow.test.ts88-105](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/package-acceptance-workflow.test.ts#L88-L105)

**Sources:** [docs/ci.md15-35](https://github.com/openclaw/openclaw/blob/fbdf5937/docs/ci.md?plain=1#L15-L35) [test/scripts/package-acceptance-workflow.test.ts88-105](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/package-acceptance-workflow.test.ts#L88-L105)

## Crabbox & Remote Validation

OpenClaw uses **Crabbox**, a transport and orchestration surface for remote validation across Linux, macOS, and Windows [.agents/skills/crabbox/SKILL.md3-10](https://github.com/openclaw/openclaw/blob/fbdf5937/.agents/skills/crabbox/SKILL.md?plain=1#L3-L10)

### Backend Providers

- AWS Crabbox : Direct provider ( cbx_... IDs) used for persistent direct-provider leases and macOS targets .agents/skills/crabbox/SKILL.md 14-57
- Blacksmith Testbox : Delegated provider ( tbx_... IDs) preferred for broad pnpm gates and CI-parity checks .agents/skills/crabbox/SKILL.md 16-57

### Remote Hydration

The `Crabbox Hydrate` workflow prepares these remote environments by installing Node.js, `pnpm`, and Docker [.github/workflows/crabbox-hydrate.yml52-190](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/crabbox-hydrate.yml#L52-L190) It ensures that the remote environment matches the local developer setup for consistent proof.

**Sources:** [.agents/skills/crabbox/SKILL.md1-60](https://github.com/openclaw/openclaw/blob/fbdf5937/.agents/skills/crabbox/SKILL.md?plain=1#L1-L60) [.github/workflows/crabbox-hydrate.yml42-190](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/crabbox-hydrate.yml#L42-L190)

# Key Implementation Details

## Data Flow: From Commit to Validated Artifact

```

```

This diagram maps how a commit triggers the `preflight` logic to dispatch platform-specific jobs, which in turn invoke specialized scripts or remote orchestration via Crabbox.

**Sources:** [.github/workflows/ci.yml37-77](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/workflows/ci.yml#L37-L77) [scripts/openclaw-cross-os-release-checks.ts1-40](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/openclaw-cross-os-release-checks.ts#L1-L40) [.agents/skills/crabbox/SKILL.md1-20](https://github.com/openclaw/openclaw/blob/fbdf5937/.agents/skills/crabbox/SKILL.md?plain=1#L1-L20)

## Node.js Environment Setup

The pipeline uses a composite action `.github/actions/setup-pnpm-store-cache` to ensure consistency. It:

1. Installs Node.js from the requested version .github/actions/setup-pnpm-store-cache/action.yml 54-56
2. Configures pnpm using corepack based on the packageManager field in package.json .github/actions/setup-pnpm-store-cache/action.yml 65-80
3. Restores the pnpm store cache to speed up dependency installation .github/actions/setup-pnpm-store-cache/action.yml 92-102

**Sources:** [.github/actions/setup-pnpm-store-cache/action.yml1-109](https://github.com/openclaw/openclaw/blob/fbdf5937/.github/actions/setup-pnpm-store-cache/action.yml#L1-L109) [test/scripts/package-acceptance-workflow.test.ts88-114](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/package-acceptance-workflow.test.ts#L88-L114)

## Release Check Heartbeats

To prevent CI timeouts during long-running release checks (e.g., waiting for a Windows Gateway to become ready), the `openclaw-cross-os-release-checks.ts` script implements a heartbeat mechanism. It prints status updates based on `CROSS_OS_COMMAND_HEARTBEAT_SECONDS` (default 60s) to satisfy the GitHub Actions "no output" timeout [scripts/openclaw-cross-os-release-checks.ts166-169](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/openclaw-cross-os-release-checks.ts#L166-L169)

**Sources:** [scripts/openclaw-cross-os-release-checks.ts166-169](https://github.com/openclaw/openclaw/blob/fbdf5937/scripts/openclaw-cross-os-release-checks.ts#L166-L169) [test/scripts/openclaw-cross-os-release-checks.test.ts199-201](https://github.com/openclaw/openclaw/blob/fbdf5937/test/scripts/openclaw-cross-os-release-checks.test.ts#L199-L201)
