CI pipeline

OpenClaw CI runs on every push to

and every pull request. The job classifies the diff and turns expensive lanes off when only unrelated areas changed. Manual runs intentionally bypass smart scoping and fan out the full graph for release candidates and broad validation. Android lanes stay opt-in through . Release-only plugin coverage lives in the separate

text

Copy

Plugin Prerelease

workflow and only runs from

text

Copy

Full Release Validation

or an explicit manual dispatch.

Pipeline overview

Fail-fast order

1. text

   Copy

   preflight
   decides which lanes exist at all. The
   text

   Copy

   docs-scope
   and
   text

   Copy

   changed-scope
   logic are steps inside this job, not standalone jobs.
2. text

   Copy

   security-scm-fast
   ,
   text

   Copy

   security-dependency-audit
   ,
   text

   Copy

   security-fast
   ,
   text

   Copy

   check
   ,
   text

   Copy

   check-additional
   ,
   text

   Copy

   check-docs
   , and
   text

   Copy

   skills-python
   fail quickly without waiting on the heavier artifact and platform matrix jobs.
3. text

   Copy

   build-artifacts
   overlaps with the fast Linux lanes so downstream consumers can start as soon as the shared build is ready.
4. Heavier platform and runtime lanes fan out after that:
   text

   Copy

   checks-fast-core
   ,
   text

   Copy

   checks-fast-contracts-channels
   ,
   text

   Copy

   checks-node-core-test
   ,
   text

   Copy

   checks
   ,
   text

   Copy

   checks-windows
   ,
   text

   Copy

   macos-node
   ,
   text

   Copy

   macos-swift
   , and
   text

   Copy

   android
   .

GitHub may mark superseded jobs as

when a newer push lands on the same PR or ref. Treat that as CI noise unless the newest run for the same ref is also failing. Aggregate shard checks use so they still report normal shard failures but do not queue after the whole workflow has already been superseded. The automatic CI concurrency key is versioned () so a GitHub-side zombie in an old queue group cannot indefinitely block newer main runs. Manual full-suite runs use and do not cancel in-progress runs.

Scope and routing

Scope logic lives in

and is covered by unit tests in . Manual dispatch skips changed-scope detection and makes the preflight manifest act as if every scoped area changed.

• CI workflow edits validate the Node CI graph plus workflow linting, but do not force Windows, Android, or macOS native builds by themselves; those platform lanes stay scoped to platform source changes.
• CI routing-only edits, selected cheap core-test fixture edits, and narrow plugin contract helper/test-routing edits use a fast Node-only manifest path:
  text

  Copy

  preflight
  , security, and a single
  text

  Copy

  checks-fast-core
  task. That path skips build artifacts, Node 22 compatibility, channel contracts, full core shards, bundled-plugin shards, and additional guard matrices when the change is limited to the routing or helper surfaces the fast task exercises directly.
• Windows Node checks are scoped to Windows-specific process/path wrappers, npm/pnpm/UI runner helpers, package manager config, and the CI workflow surfaces that execute that lane; unrelated source, plugin, install-smoke, and test-only changes stay on the Linux Node lanes.

The slowest Node test families are split or balanced so each job stays small without over-reserving runners: channel contracts run as three weighted shards, small core unit lanes are paired, auto-reply runs as four balanced workers (with the reply subtree split into agent-runner, dispatch, and commands/state-routing shards), and agentic gateway/plugin configs are spread across the existing source-only agentic Node jobs instead of waiting on built artifacts. Broad browser, QA, media, and miscellaneous plugin tests use their dedicated Vitest configs instead of the shared plugin catch-all. Include-pattern shards record timing entries using the CI shard name, so

can distinguish a whole config from a filtered shard. keeps package-boundary compile/canary work together and separates runtime topology architecture from gateway watch coverage; the boundary guard shard runs its small independent guards concurrently inside one job. Gateway watch, channel tests, and the core support-boundary shard run concurrently inside after and are already built.

Android CI runs both

and and then builds the Play debug APK. The third-party flavor has no separate source set or manifest; its unit-test lane still compiles the flavor with the SMS/call-log BuildConfig flags, while avoiding a duplicate debug APK packaging job on every Android-relevant push.

The

shard runs (a production Knip dependency-only pass pinned to the latest Knip version, with pnpm's minimum release age disabled for the install) and , which compares Knip's production unused-file findings against . The unused-file guard fails when a PR adds a new unreviewed unused file or leaves a stale allowlist entry, while preserving intentional dynamic plugin, generated, build, live-test, and package bridge surfaces that Knip cannot resolve statically.

Manual dispatches

Manual CI dispatches run the same job graph as normal CI but force every non-Android scoped lane on: Linux Node shards, bundled-plugin shards, channel contracts, Node 22 compatibility,

, , build smoke, docs checks, Python skills, Windows, macOS, and Control UI i18n. Standalone manual CI dispatches run Android only with ; the full release umbrella enables Android by passing . Plugin prerelease static checks, the release-only shard, the full extension batch sweep, and plugin prerelease Docker lanes are excluded from CI. The Docker prerelease suite runs only when dispatches the separate workflow with the release-validation gate enabled.

Manual runs use a unique concurrency group so a release-candidate full suite is not cancelled by another push or PR run on the same ref. The optional

input lets a trusted caller run that graph against a branch, tag, or full commit SHA while using the workflow file from the selected dispatch ref.

bash
Copy
gh workflow run ci.yml --ref release/YYYY.M.D
gh workflow run ci.yml --ref main -f target_ref=<branch-or-sha> -f include_android=true
gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>

Runners

Local equivalents

bash
Copy
pnpm changed:lanes                            # inspect the local changed-lane classifier for origin/main...HEAD
pnpm check:changed                            # smart local check gate: changed typecheck/lint/guards by boundary lane
pnpm check                                    # fast local gate: prod tsgo + sharded lint + parallel fast guards
pnpm check:test-types
pnpm check:timed                              # same gate with per-stage timings
pnpm build:strict-smoke
pnpm check:architecture
pnpm test:gateway:watch-regression
pnpm test                                     # vitest tests
pnpm test:changed                             # cheap smart changed Vitest targets
pnpm test:channels
pnpm test:contracts:channels
pnpm check:docs                               # docs format + lint + broken links
pnpm build                                    # build dist when CI artifact/build-smoke lanes matter
pnpm ci:timings                               # summarize the latest origin/main push CI run
pnpm ci:timings:recent                        # compare recent successful main CI runs
node scripts/ci-run-timings.mjs <run-id>      # summarize wall time, queue time, and slowest jobs
node scripts/ci-run-timings.mjs --latest-main # ignore issue/comment noise and choose origin/main push CI
node scripts/ci-run-timings.mjs --recent 10   # compare recent successful main CI runs
pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json
pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json

Full Release Validation

is the manual umbrella workflow for "run everything before release." It accepts a branch, tag, or full commit SHA, dispatches the manual workflow with that target, dispatches for release-only plugin/package/static/Docker proof, and dispatches for install smoke, package acceptance, Docker release-path suites, live/E2E, OpenWebUI, QA Lab parity, Matrix, and Telegram lanes. It can also run the post-publish workflow when a published package spec is provided.

See Full release validation for the stage matrix, exact workflow job names, profile differences, artifacts, and focused rerun handles.

controls live/provider breadth passed into release checks. The manual release workflows default to ; use only when you intentionally want the broad advisory provider/media matrix.

• text

  Copy

  minimum
  keeps the fastest OpenAI/core release-critical lanes.
• text

  Copy

  stable
  adds the stable provider/backend set.
• text

  Copy

  full
  runs the broad advisory provider/media matrix.

The umbrella records the dispatched child run ids, and the final

job re-checks current child run conclusions and appends slowest-job tables for each child run. If a child workflow is rerun and turns green, rerun only the parent verifier job to refresh the umbrella result and timing summary.

For recovery, both

and accept . Use for a release candidate, for only the normal full CI child, for only the plugin prerelease child, for every release child, or a narrower group: , , , , , , , or on the umbrella. This keeps a failed release box rerun bounded after a focused fix.

uses the trusted workflow ref to resolve the selected ref once into a tarball, then passes that artifact to both the live/E2E release-path Docker workflow and the package acceptance shard. That keeps the package bytes consistent across release boxes and avoids repacking the same candidate in multiple child jobs.

Duplicate

runs for and supersede the older umbrella. The parent monitor cancels any child workflow it has already dispatched when the parent is cancelled, so newer main validation does not sit behind a stale two-hour release-check run. Release branch/tag validation and focused rerun groups keep .

Live and E2E shards

The release live/E2E child keeps broad native

coverage, but it runs it as named shards through instead of one serial job:

• text

  Copy

  native-live-src-agents
• text

  Copy

  native-live-src-gateway-core
• provider-filtered
  text

  Copy

  native-live-src-gateway-profiles
  jobs
• text

  Copy

  native-live-src-gateway-backends
• text

  Copy

  native-live-test
• text

  Copy

  native-live-extensions-a-k
• text

  Copy

  native-live-extensions-l-n
• text

  Copy

  native-live-extensions-openai
• text

  Copy

  native-live-extensions-o-z-other
• text

  Copy

  native-live-extensions-xai
• split media audio/video shards and provider-filtered music shards

That keeps the same file coverage while making slow live provider failures easier to rerun and diagnose. The aggregate

, , and shard names remain valid for manual one-shot reruns.

The native live media shards run in

, built by the workflow. That image preinstalls and ; media jobs only verify the binaries before setup. Keep Docker-backed live suites on normal Blacksmith runners — container jobs are the wrong place to launch nested Docker tests.

Docker-backed live model/backend shards use a separate shared

image per selected commit. The live release workflow builds and pushes that image once, then the Docker live model, provider-sharded gateway, CLI backend, ACP bind, and Codex harness shards run with . Gateway Docker shards carry explicit script-level caps below the workflow job timeout so a stuck container or cleanup path fails fast instead of consuming the whole release-check budget. If those shards rebuild the full source Docker target independently, the release run is misconfigured and will waste wall clock on duplicate image builds.

Package Acceptance

Use

when the question is "does this installable OpenClaw package work as a product?" It is different from normal CI: normal CI validates the source tree, while package acceptance validates a single tarball through the same Docker E2E harness users exercise after install or update.

Jobs

1. text

   Copy

   resolve_package
   checks out
   text

   Copy

   workflow_ref
   , resolves one package candidate, writes
   text

   Copy

   .artifacts/docker-e2e-package/openclaw-current.tgz
   , writes
   text

   Copy

   .artifacts/docker-e2e-package/package-candidate.json
   , uploads both as the
   text

   Copy

   package-under-test
   artifact, and prints the source, workflow ref, package ref, version, SHA-256, and profile in the GitHub step summary.
2. text

   Copy

   docker_acceptance
   calls
   text

   Copy

   openclaw-live-and-e2e-checks-reusable.yml
   with
   text

   Copy

   ref=workflow_ref
   and
   text

   Copy

   package_artifact_name=package-under-test
   . The reusable workflow downloads that artifact, validates the tarball inventory, prepares package-digest Docker images when needed, and runs the selected Docker lanes against that package instead of packing the workflow checkout. When a profile selects multiple targeted
   text

   Copy

   docker_lanes
   , the reusable workflow prepares the package and shared images once, then fans those lanes out as parallel targeted Docker jobs with unique artifacts.
3. text

   Copy

   package_telegram
   optionally calls
   text

   Copy

   NPM Telegram Beta E2E
   . It runs when
   text

   Copy

   telegram_mode
   is not
   text

   Copy

   none
   and installs the same
   text

   Copy

   package-under-test
   artifact when Package Acceptance resolved one; standalone Telegram dispatch can still install a published npm spec.
4. text

   Copy

   summary
   fails the workflow if package resolution, Docker acceptance, or the optional Telegram lane failed.

Candidate sources

• text

  Copy

  source=npm
  accepts only
  text

  Copy

  openclaw@beta
  ,
  text

  Copy

  openclaw@latest
  , or an exact OpenClaw release version such as
  text

  Copy

  openclaw@2026.4.27-beta.2
  . Use this for published beta/stable acceptance.
• text

  Copy

  source=ref
  packs a trusted
  text

  Copy

  package_ref
  branch, tag, or full commit SHA. The resolver fetches OpenClaw branches/tags, verifies the selected commit is reachable from repository branch history or a release tag, installs deps in a detached worktree, and packs it with
  text

  Copy

  scripts/package-openclaw-for-docker.mjs
  .
• text

  Copy

  source=url
  downloads an HTTPS
  text

  Copy

  .tgz
  ;
  text

  Copy

  package_sha256
  is required.
• text

  Copy

  source=artifact
  downloads one
  text

  Copy

  .tgz
  from
  text

  Copy

  artifact_run_id
  and
  text

  Copy

  artifact_name
  ;
  text

  Copy

  package_sha256
  is optional but should be supplied for externally shared artifacts.

Keep

and separate. is the trusted workflow/harness code that runs the test. is the source commit that gets packed when . This lets the current test harness validate older trusted source commits without running old workflow logic.

Suite profiles

• text

  Copy

  smoke
  —
  text

  Copy

  npm-onboard-channel-agent
  ,
  text

  Copy

  gateway-network
  ,
  text

  Copy

  config-reload
• text

  Copy

  package
  —
  text

  Copy

  npm-onboard-channel-agent
  ,
  text

  Copy

  doctor-switch
  ,
  text

  Copy

  update-channel-switch
  ,
  text

  Copy

  upgrade-survivor
  ,
  text

  Copy

  published-upgrade-survivor
  ,
  text

  Copy

  bundled-channel-deps-compat
  ,
  text

  Copy

  plugins-offline
  ,
  text

  Copy

  plugin-update
• text

  Copy

  product
  —
  text

  Copy

  package
  plus
  text

  Copy

  mcp-channels
  ,
  text

  Copy

  cron-mcp-cleanup
  ,
  text

  Copy

  openai-web-search-minimal
  ,
  text

  Copy

  openwebui
• text

  Copy

  full
  — full Docker release-path chunks with OpenWebUI
• text

  Copy

  custom
  — exact
  text

  Copy

  docker_lanes
  ; required when
  text

  Copy

  suite_profile=custom

The

profile uses offline plugin coverage so published-package validation is not gated on live ClawHub availability. The optional Telegram lane reuses the artifact in , with the published npm spec path kept for standalone dispatches.

Release checks call Package Acceptance with

, , , , , and . Release-path Docker chunks cover the overlapping package/update/plugin lanes; Package Acceptance keeps the artifact-native bundled-channel compat, offline plugin, and Telegram proof against the same resolved package tarball. Cross-OS release checks still cover OS-specific onboarding, installer, and platform behavior; package/update product validation should start with Package Acceptance. The Docker lane validates one published package baseline per run. In Package Acceptance, the resolved tarball is always the candidate and selects the published baseline, defaulting to ; failed-lane rerun commands preserve that baseline. Local runs can set to an exact package such as . The published lane configures the baseline with a baked command recipe, then records recipe steps in . Broader previous-version coverage should shard Package Acceptance across exact values. The Windows packaged and installer fresh lanes also verify that an installed package can import a browser-control override from a raw absolute Windows path. The OpenAI cross-OS agent-turn smoke defaults to when set, otherwise , so the install and gateway proof stays fast and deterministic.

Legacy compatibility windows

Package Acceptance has bounded legacy-compatibility windows for already-published packages. Packages through

, including , may use the compatibility path:

• known private QA entries in
  text

  Copy

  dist/postinstall-inventory.json
  may point at tarball-omitted files;
• text

  Copy

  doctor-switch
  may skip the
  text

  Copy

  gateway install --wrapper
  persistence subcase when the package does not expose that flag;
• text

  Copy

  update-channel-switch
  may prune missing
  text

  Copy

  pnpm.patchedDependencies
  from the tarball-derived fake git fixture and may log missing persisted
  text

  Copy

  update.channel
  ;
• plugin smokes may read legacy install-record locations or accept missing marketplace install-record persistence;
• text

  Copy

  plugin-update
  may allow config metadata migration while still requiring the install record and no-reinstall behavior to stay unchanged.

The published

package may also warn for local build metadata stamp files that were already shipped. Later packages must satisfy the modern contracts; the same conditions fail instead of warn or skip.

Examples

bash
Copy
# Validate the current beta package with product-level coverage.
gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=npm \
  -f package_spec=openclaw@beta \
  -f suite_profile=product \
  -f telegram_mode=mock-openai

# Pack and validate a release branch with the current harness.
gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=ref \
  -f package_ref=release/YYYY.M.D \
  -f suite_profile=package \
  -f telegram_mode=mock-openai

# Validate a tarball URL. SHA-256 is mandatory for source=url.
gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=url \
  -f package_url=https://example.com/openclaw-current.tgz \
  -f package_sha256=<64-char-sha256> \
  -f suite_profile=smoke

# Reuse a tarball uploaded by another Actions run.
gh workflow run package-acceptance.yml \
  --ref main \
  -f workflow_ref=main \
  -f source=artifact \
  -f artifact_run_id=<run-id> \
  -f artifact_name=package-under-test \
  -f suite_profile=custom \
  -f docker_lanes='install-e2e plugin-update'

When debugging a failed package acceptance run, start at the

summary to confirm the package source, version, and SHA-256. Then inspect the child run and its Docker artifacts: , , lane logs, phase timings, and rerun commands. Prefer rerunning the failed package profile or exact Docker lanes instead of rerunning full release validation.

Install smoke

The separate

workflow reuses the same scope script through its own job. It splits smoke coverage into and .

• Fast path runs for pull requests touching Docker/package surfaces, bundled plugin package/manifest changes, or core plugin/channel/gateway/Plugin SDK surfaces that the Docker smoke jobs exercise. Source-only bundled plugin changes, test-only edits, and docs-only edits do not reserve Docker workers. The fast path builds the root Dockerfile image once, checks the CLI, runs the agents delete shared-workspace CLI smoke, runs the container gateway-network e2e, verifies a bundled extension build arg, and runs the bounded bundled-plugin Docker profile under a 240-second aggregate command timeout (each scenario's Docker run capped separately).
• Full path keeps QR package install and installer Docker/update coverage for nightly scheduled runs, manual dispatches, workflow-call release checks, and pull requests that truly touch installer/package/Docker surfaces. In full mode, install-smoke prepares or reuses one target-SHA GHCR root Dockerfile smoke image, then runs QR package install, root Dockerfile/gateway smokes, installer/update smokes, and the fast bundled-plugin Docker E2E as separate jobs so installer work does not wait behind the root image smokes.

pushes (including merge commits) do not force the full path; when changed-scope logic would request full coverage on a push, the workflow keeps the fast Docker smoke and leaves the full install smoke to nightly or release validation.

The slow Bun global install image-provider smoke is separately gated by

. It runs on the nightly schedule and from the release checks workflow, and manual dispatches can opt into it, but pull requests and pushes do not. QR and installer Docker tests keep their own install-focused Dockerfiles.

Local Docker E2E

prebuilds one shared live-test image, packs OpenClaw once as an npm tarball, and builds two shared images:

• a bare Node/Git runner for installer/update/plugin-dependency lanes;
• a functional image that installs the same tarball into
  text

  Copy

  /app
  for normal functionality lanes.

Docker lane definitions live in

, planner logic lives in , and the runner only executes the selected plan. The scheduler selects the image per lane with and , then runs lanes with .

Tunables

A lane heavier than its effective cap can still start from an empty pool, then runs alone until it releases capacity. The local aggregate preflights Docker, removes stale OpenClaw E2E containers, emits active-lane status, persists lane timings for longest-first ordering, and stops scheduling new pooled lanes after the first failure by default.

Reusable live/E2E workflow

The reusable live/E2E workflow asks

which package, image kind, live image, lane, and credential coverage is required. then converts that plan into GitHub outputs and summaries. It either packs OpenClaw through , downloads a current-run package artifact, or downloads a package artifact from ; validates the tarball inventory; builds and pushes package-digest-tagged bare/functional GHCR Docker E2E images through Blacksmith's Docker layer cache when the plan needs package-installed lanes; and reuses provided / inputs or existing package-digest images instead of rebuilding. Docker image pulls are retried with a bounded 180-second per-attempt timeout so a stuck registry/cache stream retries quickly instead of consuming most of the CI critical path.

Release-path chunks

Release Docker coverage runs smaller chunked jobs with

so each chunk pulls only the image kind it needs and executes multiple lanes through the same weighted scheduler:

• text

  Copy

  OPENCLAW_DOCKER_ALL_PROFILE=release-path
• text

  Copy

  OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h | bundled-channels

Current release Docker chunks are

, , , , , , through , , , , , and . The aggregate chunk remains available for manual one-shot reruns, and , , and remain aggregate plugin/runtime aliases. The lane alias remains the aggregate manual rerun alias for both provider installer lanes. The chunk runs split and lanes rather than the serial all-in-one lane.

OpenWebUI is folded into

when full release-path coverage requests it, and keeps a standalone chunk only for OpenWebUI-only dispatches. Bundled-channel update lanes retry once for transient npm network failures.

Each chunk uploads

with lane logs, timings, , , phase timings, scheduler plan JSON, slow-lane tables, and per-lane rerun commands. The workflow input runs selected lanes against the prepared images instead of the chunk jobs, which keeps failed-lane debugging bounded to one targeted Docker job and prepares, downloads, or reuses the package artifact for that run; if a selected lane is a live Docker lane, the targeted job builds the live-test image locally for that rerun. Generated per-lane GitHub rerun commands include , , and prepared image inputs when those values exist, so a failed lane can reuse the exact package and images from the failed run.

bash
Copy
pnpm test:docker:rerun <run-id>      # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary>   # slow-lane and phase critical-path summaries

The scheduled live/E2E workflow runs the full release-path Docker suite daily.

Plugin Prerelease

is more expensive product/package coverage, so it is a separate workflow dispatched by or by an explicit operator. Normal pull requests, pushes, and standalone manual CI dispatches keep that suite off. It balances bundled plugin tests across eight extension workers; those extension shard jobs run up to two plugin config groups at a time with one Vitest worker per group and a larger Node heap so import-heavy plugin batches do not create extra CI jobs. The release-only Docker prerelease path batches targeted Docker lanes in small groups to avoid reserving dozens of runners for one-to-three-minute jobs.

QA Lab

QA Lab has dedicated CI lanes outside the main smart-scoped workflow.

• The
  text

  Copy

  Parity gate
  workflow runs on matching PR changes and manual dispatch; it builds the private QA runtime and compares the mock GPT-5.5 and Opus 4.6 agentic packs.
• The
  text

  Copy

  QA-Lab - All Lanes
  workflow runs nightly on
  text

  Copy

  main
  and on manual dispatch; it fans out the mock parity gate, live Matrix lane, and live Telegram and Discord lanes as parallel jobs. Live jobs use the
  text

  Copy

  qa-live-shared
  environment, and Telegram/Discord use Convex leases.

Release checks run Matrix and Telegram live transport lanes with the deterministic mock provider and mock-qualified models (

and ) so the channel contract is isolated from live model latency and normal provider-plugin startup. The live transport gateway disables memory search because QA parity covers memory behavior separately; provider connectivity is covered by the separate live model, native provider, and Docker provider suites.

Matrix uses

for scheduled and release gates, adding only when the checked-out CLI supports it. The CLI default and manual workflow input remain ; manual dispatch always shards full Matrix coverage into , , , , and jobs.

also runs the release-critical QA Lab lanes before release approval; its QA parity gate runs the candidate and baseline packs as parallel lane jobs, then downloads both artifacts into a small report job for the final parity comparison.

Do not put the PR landing path behind

unless the change actually touches QA runtime, model-pack parity, or a surface the parity workflow owns. For normal channel, config, docs, or unit-test fixes, treat it as an optional signal and follow the scoped CI/check evidence instead.

CodeQL

The

workflow is intentionally a narrow first-pass security scanner, not the full repository sweep. Daily, manual, and non-draft pull request guard runs scan Actions workflow code plus the highest-risk JavaScript/TypeScript surfaces with high-confidence security queries filtered to high/critical .

The pull request guard stays light: it only starts for changes under

, , , , or , and it runs the same high-confidence security matrix as the scheduled workflow. Android and macOS CodeQL stay out of PR defaults.

Security categories

Platform-specific security shards

• text

  Copy

  CodeQL Android Critical Security
  — scheduled Android security shard. Builds the Android app manually for CodeQL on the smallest Blacksmith Linux runner accepted by workflow sanity. Uploads under
  text

  Copy

  /codeql-critical-security/android
  .
• text

  Copy

  CodeQL macOS Critical Security
  — weekly/manual macOS security shard. Builds the macOS app manually for CodeQL on Blacksmith macOS, filters dependency build results out of uploaded SARIF, and uploads under
  text

  Copy

  /codeql-critical-security/macos
  . Kept outside daily defaults because macOS build dominates runtime even when clean.

Critical Quality categories

is the matching non-security shard. It runs only error-severity, non-security JavaScript/TypeScript quality queries over narrow high-value surfaces on the smaller Blacksmith Linux runner. Its pull request guard is intentionally smaller than the scheduled profile: non-draft PRs only run the matching , , , , , , , , , , , and shards for agent command/model/tool execution and reply dispatch code, config schema/migration/IO code, auth/secrets/sandbox/security code, core channel and bundled channel plugin runtime, gateway protocol/server-method, memory runtime/SDK glue, MCP/process/outbound delivery, provider runtime/model catalog, session diagnostics/delivery queues, plugin loader, Plugin SDK/package-contract, or Plugin SDK reply runtime changes. CodeQL config and quality workflow changes run all twelve PR quality shards.

Manual dispatch accepts:

text
Copy
profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary

The narrow profiles are teaching/iteration hooks for running one quality shard in isolation.

Quality stays separate from security so quality findings can be scheduled, measured, disabled, or expanded without obscuring security signal. Swift, Python, and bundled-plugin CodeQL expansion should be added back as scoped or sharded follow-up work only after the narrow profiles have stable runtime and signal.

Maintenance workflows

Docs Agent

The

workflow is an event-driven Codex maintenance lane for keeping existing docs aligned with recently landed changes. It has no pure schedule: a successful non-bot push CI run on can trigger it, and manual dispatch can run it directly. Workflow-run invocations skip when has moved on or when another non-skipped Docs Agent run was created in the last hour. When it runs, it reviews the commit range from the previous non-skipped Docs Agent source SHA to current , so one hourly run can cover all main changes accumulated since the last docs pass.

Test Performance Agent

The

workflow is an event-driven Codex maintenance lane for slow tests. It has no pure schedule: a successful non-bot push CI run on can trigger it, but it skips if another workflow-run invocation already ran or is running that UTC day. Manual dispatch bypasses that daily activity gate. The lane builds a full-suite grouped Vitest performance report, lets Codex make only small coverage-preserving test performance fixes instead of broad refactors, then reruns the full-suite report and rejects changes that reduce the passing baseline test count. If the baseline has failing tests, Codex may fix only obvious failures and the after-agent full-suite report must pass before anything is committed. When advances before the bot push lands, the lane rebases the validated patch, reruns , and retries the push; conflicting stale patches are skipped. It uses GitHub-hosted Ubuntu so the Codex action can keep the same drop-sudo safety posture as the docs agent.

Duplicate PRs After Merge

The

workflow is a manual maintainer workflow for post-land duplicate cleanup. It defaults to dry-run and only closes explicitly listed PRs when . Before mutating GitHub, it verifies that the landed PR is merged and that each duplicate has either a shared referenced issue or overlapping changed hunks.

bash
Copy
gh workflow run duplicate-after-merge.yml \
  -f landed_pr=70532 \
  -f duplicate_prs='70530,70592' \
  -f apply=true

Local check gates and changed routing

Local changed-lane logic lives in

and is executed by . That local check gate is stricter about architecture boundaries than the broad CI platform scope:

• core production changes run core prod and core test typecheck plus core lint/guards;
• core test-only changes run only core test typecheck plus core lint;
• extension production changes run extension prod and extension test typecheck plus extension lint;
• extension test-only changes run extension test typecheck plus extension lint;
• public Plugin SDK or plugin-contract changes expand to extension typecheck because extensions depend on those core contracts (Vitest extension sweeps stay explicit test work);
• release metadata-only version bumps run targeted version/config/root-dependency checks;
• unknown root/config changes fail safe to all check lanes.

Local changed-test routing lives in

and is intentionally cheaper than : direct test edits run themselves, source edits prefer explicit mappings, then sibling tests and import-graph dependents. Shared group-room delivery config is one of the explicit mappings: changes to the group visible-reply config, source reply delivery mode, or the message-tool system prompt route through the core reply tests plus Discord and Slack delivery regressions so a shared default change fails before the first PR push. Use only when the change is harness-wide enough that the cheap mapped set is not a trustworthy proxy.

Testbox validation

Run Testbox from the repo root and prefer a fresh warmed box for broad proof. Before spending a slow gate on a box that was reused, expired, or just reported an unexpectedly large sync, run

inside the box first.

The sanity check fails fast when required root files such as

disappeared or when shows at least 200 tracked deletions. That usually means the remote sync state is not a trustworthy copy of the PR; stop that box and warm a fresh one instead of debugging the product test failure. For intentional large-deletion PRs, set for that sanity run.

also terminates a local Blacksmith CLI invocation that stays in the sync phase for more than five minutes without post-sync output. Set to disable that guard, or use a larger millisecond value for unusually large local diffs.

Related

• Install overview
• Development channels