Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

ci-gate: wait only for the workflows of the changed areas; add urgent label (#5995)

cua-agents[bot]b85d1c37407d
diff --git a/.github/ci-areas.json b/.github/ci-areas.json
new file mode 100644
index 0000000000..15a9dcea55
--- /dev/null
+++ b/.github/ci-areas.json
@@ -0,0 +1,428 @@
+{
+ "shared": [
+ ".github/**",
+ "*",
+ "**/Cargo.lock",
+ "**/rust-toolchain.toml",
+ "**/pnpm-lock.yaml",
+ "**/pnpm-workspace.yaml",
+ "**/package-lock.json",
+ "**/uv.lock",
+ "libs/cua/Cargo.toml",
+ "libs/cua-driver/rust/Cargo.toml",
+ "libs/cua-spacesd/Cargo.toml",
+ "libs/cua-driver/rust/.cargo/**",
+ "libs/cua/.cargo/**",
+ "libs/cua/proto/**",
+ "libs/cua/crates/cua-proto/**",
+ "libs/cua-driver/rust/crates/cua-driver-core/**",
+ "libs/cua-driver/rust/crates/cua-driver-contract/**",
+ "libs/cua/crates/cua-sandbox-core/**",
+ "scripts/ci/**",
+ "flake.nix",
+ "nix/**"
+ ],
+ "areas": {
+ "relay": {
+ "paths": [
+ "libs/cua-spacesd/crates/cua-relay/**"
+ ],
+ "workflows": [
+ "ci-cua-relay-image.yml",
+ "ci-cua-spacesd.yml",
+ "ci-lockfiles.yml",
+ "ci-spdx-headers.yml",
+ "license-check.yml"
+ ],
+ "narrowed": true
+ },
+ "spacesd": {
+ "paths": [
+ "libs/cua-spacesd/**"
+ ],
+ "workflows": [
+ "cd-image-linux.yml",
+ "ci-check-docs-image-refs.yml",
+ "ci-check-docs-links.yml",
+ "ci-cua-oci-spacesd.yml",
+ "ci-cua-relay-image.yml",
+ "ci-cua-sandbox-doctor.yml",
+ "ci-cua-sdk.yml",
+ "ci-cua-spacesd.yml",
+ "ci-elastic.yml",
+ "ci-images-spacesd-lag.yml",
+ "ci-lockfiles.yml",
+ "ci-openkoalabot-example-tauri.yml",
+ "ci-release-spacesd-pin.yml",
+ "ci-spdx-headers.yml",
+ "ci-test-python.yml",
+ "e2b-core-nightly.yml",
+ "e2e-cua-sdk.yml",
+ "license-check.yml",
+ "perf-cua-channel.yml"
+ ]
+ },
+ "driver-rust": {
+ "paths": [
+ "libs/cua-driver/rust/**"
+ ],
+ "workflows": [
+ "cd-cua-perception.yml",
+ "ci-check-docs-image-refs.yml",
+ "ci-check-docs-links.yml",
+ "ci-check-docs.yml",
+ "ci-cua-driver-contract-clients.yml",
+ "ci-cua-driver-preflight.yml",
+ "ci-cua-driver-quick.yml",
+ "ci-cua-driver-valgrind.yml",
+ "ci-cua-perception-release.yml",
+ "ci-cua-s1-weights.yml",
+ "ci-cua-sandbox-doctor.yml",
+ "ci-cua-spacesd.yml",
+ "ci-driver-mcp-candidate.yml",
+ "ci-lockfiles.yml",
+ "ci-nix-linux.yml",
+ "ci-platform-linux-portability.yml",
+ "ci-rust-format.yml",
+ "ci-rust-linux.yml",
+ "ci-rust-macos.yml",
+ "ci-rust-windows.yml",
+ "ci-spdx-headers.yml",
+ "ci-swift-linker.yml",
+ "ci-test-scripts.yml",
+ "ci-ts-cursor-motion.yml",
+ "clawhub-cua-driver.yml",
+ "e2e-cua-sdk.yml",
+ "e2e-rust-linux.yml",
+ "fuzz-cua-driver.yml",
+ "license-check.yml",
+ "smoke-cua-driver-live.yml"
+ ]
+ },
+ "driver": {
+ "paths": [
+ "libs/cua-driver/**",
+ "libs/cua-driver-bench/**"
+ ],
+ "workflows": [
+ "cd-cua-perception.yml",
+ "ci-check-docs-image-refs.yml",
+ "ci-check-docs-links.yml",
+ "ci-check-docs.yml",
+ "ci-cua-driver-bench.yml",
+ "ci-cua-driver-contract-clients.yml",
+ "ci-cua-driver-preflight.yml",
+ "ci-cua-driver-quick.yml",
+ "ci-cua-driver-valgrind.yml",
+ "ci-cua-perception-release.yml",
+ "ci-cua-s1-weights.yml",
+ "ci-cua-sandbox-doctor.yml",
+ "ci-cua-spacesd.yml",
+ "ci-driver-mcp-candidate.yml",
+ "ci-hyprland-plugin.yml",
+ "ci-jev-use.yml",
+ "ci-lockfiles.yml",
+ "ci-nix-linux.yml",
+ "ci-platform-linux-portability.yml",
+ "ci-rust-format.yml",
+ "ci-rust-linux.yml",
+ "ci-rust-macos.yml",
+ "ci-rust-windows.yml",
+ "ci-spdx-headers.yml",
+ "ci-swift-linker.yml",
+ "ci-test-scripts.yml",
+ "ci-ts-cursor-motion.yml",
+ "clawhub-cua-driver.yml",
+ "docs-driver-first-run-smoke.yml",
+ "e2e-cua-sdk.yml",
+ "e2e-rust-linux.yml",
+ "fuzz-cua-driver.yml",
+ "license-check.yml",
+ "nightly-hyprland-plugin-requalify.yml",
+ "smoke-cua-driver-live.yml"
+ ]
+ },
+ "cua": {
+ "paths": [
+ "libs/cua/**",
+ "tests/e2e/**"
+ ],
+ "workflows": [
+ "cd-image-linux.yml",
+ "cd-image-omarchy.yml",
+ "chaos-cua-compat.yml",
+ "ci-check-docs-image-refs.yml",
+ "ci-check-docs-links.yml",
+ "ci-check-docs.yml",
+ "ci-cua-byoc.yml",
+ "ci-cua-compat-daytona.yml",
+ "ci-cua-compat-modal.yml",
+ "ci-cua-compat.yml",
+ "ci-cua-contrib.yml",
+ "ci-cua-microvm.yml",
+ "ci-cua-oci-spacesd.yml",
+ "ci-cua-proto.yml",
+ "ci-cua-relay-image.yml",
+ "ci-cua-sandbox-doctor.yml",
+ "ci-cua-sdk.yml",
+ "ci-cua-spaces-macos.yml",
+ "ci-cua-spaces-web.yml",
+ "ci-cua-spaces.yml",
+ "ci-cua-spacesd-html5.yml",
+ "ci-cua-spacesd.yml",
+ "ci-elastic.yml",
+ "ci-lockfiles.yml",
+ "ci-openkoalabot-example-tauri.yml",
+ "ci-pi-durable-crash.yml",
+ "ci-spdx-headers.yml",
+ "ci-test-python.yml",
+ "ci-vm-density.yml",
+ "docs-compile-lanes.yml",
+ "docs-nightly.yml",
+ "docs-page-tests.yml",
+ "e2b-bindings.yml",
+ "e2b-core-nightly.yml",
+ "e2e-cua-sdk.yml",
+ "license-check.yml",
+ "nightly-build.yml",
+ "nightly-e2b-rollouts.yml",
+ "nightly-fork-batch.yml",
+ "nightly-qemu-fork.yml",
+ "nightly-qemu-ready.yml",
+ "nightly-qemu-vmm.yml",
+ "perf-cua-channel.yml",
+ "space-egress-nightly.yml"
+ ]
+ },
+ "images": {
+ "paths": [
+ "libs/images/**",
+ "scripts/images/**"
+ ],
+ "workflows": [
+ "cd-bench-images.yml",
+ "cd-image-linux.yml",
+ "cd-image-macos.yml",
+ "cd-image-omarchy.yml",
+ "cd-image-runtime-gvisor.yml",
+ "ci-check-docs-image-refs.yml",
+ "ci-check-docs-links.yml",
+ "ci-check-docs.yml",
+ "ci-cua-spaces-macos.yml",
+ "ci-cua-spacesd.yml",
+ "ci-images-chromium-pin.yml",
+ "ci-images-spacesd-lag.yml",
+ "ci-lockfiles.yml",
+ "ci-spdx-headers.yml",
+ "e2b-core-nightly.yml",
+ "e2e-cua-sdk.yml",
+ "license-check.yml",
+ "nightly-qemu-ready.yml",
+ "perf-cua-channel.yml"
+ ]
+ },
+ "spaces-web": {
+ "paths": [
+ "apps/cua-spaces-web/**",
+ "apps/cua-spaces-desktop/**"
+ ],
+ "workflows": [
+ "ci-check-docs-links.yml",
+ "ci-cua-spaces-macos.yml",
+ "ci-cua-spaces-web.yml",
+ "ci-lockfiles.yml",
+ "ci-spdx-headers.yml",
+ "ci-test-scripts.yml",
+ "license-check.yml"
+ ]
+ },
+ "spaces-app": {
+ "paths": [
+ "apps/cua-spaces/**"
+ ],
+ "workflows": [
+ "ci-check-docs-links.yml",
+ "ci-cua-spaces-web.yml",
+ "ci-cua-spaces.yml",
+ "ci-installers.yml",
+ "ci-lockfiles.yml",
+ "ci-spdx-headers.yml",
+ "license-check.yml"
+ ]
+ },
+ "spaces-macos": {
+ "paths": [
+ "apps/cua-spaces-macos/**"
+ ],
+ "workflows": [
+ "ci-check-docs-links.yml",
+ "ci-cua-spaces-macos.yml",
+ "ci-cua-spaces-web.yml",
+ "ci-lockfiles.yml",
+ "ci-spdx-headers.yml",
+ "ci-test-scripts.yml",
+ "license-check.yml"
+ ]
+ },
+ "python": {
+ "paths": [
+ "libs/python/**",
+ "libs/cua-bench/**",
+ "libs/cua-bench-rl/**",
+ "libs/cua-s1/**"
+ ],
+ "workflows": [
+ "ci-bench-ale-compat.yml",
+ "ci-check-docs-image-refs.yml",
+ "ci-check-docs-links.yml",
+ "ci-check-docs.yml",
+ "ci-cua-contrib.yml",
+ "ci-cua-driver-contract-clients.yml",
+ "ci-cua-s1-weights.yml",
+ "ci-cua-s1.yml",
+ "ci-cua-sdk.yml",
+ "ci-driver-mcp-candidate.yml",
+ "ci-lint-python.yml",
+ "ci-lockfiles.yml",
+ "ci-py-agent.yml",
+ "ci-py-bench-ui.yml",
+ "ci-py-bench.yml",
+ "ci-py-core.yml",
+ "ci-py-som.yml",
+ "ci-spdx-headers.yml",
+ "ci-test-python.yml",
+ "ci-test-scripts.yml",
+ "docs-page-tests.yml",
+ "e2b-conformance.yml",
+ "e2e-cua-sdk.yml",
+ "license-check.yml"
+ ]
+ },
+ "typescript": {
+ "paths": [
+ "libs/typescript/**",
+ "libs/cuabot/**"
+ ],
+ "workflows": [
+ "ci-check-docs-image-refs.yml",
+ "ci-check-docs-links.yml",
+ "ci-container-cuabot.yml",
+ "ci-lint-typescript.yml",
+ "ci-lockfiles.yml",
+ "ci-spdx-headers.yml",
+ "ci-ts-core.yml",
+ "ci-ts-cursor-motion.yml",
+ "license-check.yml"
+ ]
+ },
+ "lume": {
+ "paths": [
+ "libs/lume/**",
+ "libs/lumier/**",
+ "libs/spaces-sdk-swift/**"
+ ],
+ "workflows": [
+ "ci-check-docs-image-refs.yml",
+ "ci-check-docs-links.yml",
+ "ci-check-docs.yml",
+ "ci-container-lumier.yml",
+ "ci-cua-sdk.yml",
+ "ci-cua-spaces-macos.yml",
+ "ci-lockfiles.yml",
+ "ci-spdx-headers.yml",
+ "ci-swift-lume.yml",
+ "ci-test-scripts.yml",
+ "license-check.yml"
+ ]
+ },
+ "containers": {
+ "paths": [
+ "libs/kasm/**",
+ "libs/qemu-docker/**",
+ "libs/xfce/**",
+ "libs/xfce-cua/**"
+ ],
+ "workflows": [
+ "ci-check-docs-image-refs.yml",
+ "ci-check-docs-links.yml",
+ "ci-container-kasm.yml",
+ "ci-container-qemu-android.yml",
+ "ci-container-qemu-linux.yml",
+ "ci-container-qemu-windows.yml",
+ "ci-container-xfce-cua.yml",
+ "ci-container-xfce.yml",
+ "ci-lockfiles.yml",
+ "ci-spdx-headers.yml",
+ "license-check.yml"
+ ]
+ },
+ "docs": {
+ "paths": [
+ "docs/**",
+ "skills/**"
+ ],
+ "workflows": [
+ "ci-check-docs-image-refs.yml",
+ "ci-check-docs-links.yml",
+ "ci-check-docs.yml",
+ "ci-cua-contrib.yml",
+ "ci-cua-sandbox-action.yml",
+ "ci-jev-use.yml",
+ "ci-lockfiles.yml",
+ "ci-public-containerdisk-refs.yml",
+ "ci-spdx-headers.yml",
+ "ci-test-scripts.yml",
+ "docs-compile-lanes.yml",
+ "docs-driver-first-run-smoke.yml",
+ "docs-mcp-corpus-parity.yml",
+ "docs-mcp-server-build-push.yml",
+ "docs-page-tests.yml",
+ "e2e-cua-sdk.yml",
+ "license-check.yml"
+ ]
+ },
+ "compat": {
+ "paths": [
+ "tests/compat/**"
+ ],
+ "workflows": [
+ "chaos-cua-compat.yml",
+ "ci-check-docs-links.yml",
+ "ci-cua-compat-daytona.yml",
+ "ci-cua-compat-e2b.yml",
+ "ci-cua-compat-modal.yml",
+ "ci-cua-compat.yml",
+ "ci-lockfiles.yml",
+ "ci-spdx-headers.yml",
+ "compat-drift.yml",
+ "e2e-compat-examples.yml",
+ "license-check.yml"
+ ]
+ },
+ "installers": {
+ "paths": [
+ "scripts/install/**"
+ ],
+ "workflows": [
+ "ci-check-docs-links.yml",
+ "ci-installers.yml",
+ "ci-lockfiles.yml",
+ "ci-spdx-headers.yml",
+ "ci-test-scripts.yml",
+ "license-check.yml"
+ ]
+ },
+ "examples": {
+ "paths": [
+ "examples/**"
+ ],
+ "workflows": [
+ "ci-check-docs-links.yml",
+ "ci-lockfiles.yml",
+ "ci-openkoalabot-example-tauri.yml",
+ "ci-spdx-headers.yml",
+ "license-check.yml"
+ ]
+ }
+ }
+}
diff --git a/.github/scripts/ci_gate_scope.py b/.github/scripts/ci_gate_scope.py
new file mode 100644
index 0000000000..25c0863173
--- /dev/null
+++ b/.github/scripts/ci_gate_scope.py
@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Decide which workflows `ci-gate` must wait for, from the paths a PR changes.
+
+The area map lives in `.github/ci-areas.json` and is documented in
+`docs/contributing/CI.md`. The rules, in order:
+
+1. A changed file that matches `shared`, or matches no area, widens the gate to
+ every workflow (the behaviour before path scoping).
+2. Otherwise each changed file belongs to the first area whose globs match it.
+3. A workflow listed under some area is required only when one of its areas
+ changed. A workflow listed under no area is always required, so a new or
+ unmapped workflow can never be skipped by accident.
+
+The gate itself never decides what a workflow's own `paths:` filter runs; it
+only decides which of the runs that exist it waits for.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+MAP_PATH = ROOT / '.github/ci-areas.json'
+WORKFLOWS = ROOT / '.github/workflows'
+
+# An urgent PR must name the Linear issue or incident that justifies the lane: a Linear key
+# of one of our teams (CUA-123, CLE-45), a Linear issue URL, or an incident reference.
+URGENT_REFERENCE = re.compile(
+ r'(?<![A-Za-z0-9])(?:CUA|CLE)-\d+\b'
+ r'|linear\.app/[\w-]+/issue/[A-Za-z0-9-]+'
+ r'|(?i:\bincident\b[^\n]{0,80}(?:#\d+|\d+|https?://\S+))'
+)
+
+
+def load_map(path: Path = MAP_PATH) -> dict:
+ return json.loads(path.read_text())
+
+
+def glob_to_regex(glob: str) -> re.Pattern:
+ out, i = [], 0
+ while i < len(glob):
+ c = glob[i]
+ if glob.startswith('**/', i):
+ out.append('(?:.*/)?')
+ i += 3
+ elif glob.startswith('**', i):
+ out.append('.*')
+ i += 2
+ elif c == '*':
+ out.append('[^/]*')
+ i += 1
+ elif c == '?':
+ out.append('[^/]')
+ i += 1
+ else:
+ out.append(re.escape(c))
+ i += 1
+ return re.compile('^' + ''.join(out) + '$')
+
+
+def matches(path: str, globs: list[str]) -> bool:
+ return any(glob_to_regex(g).match(path) for g in globs)
+
+
+def literal_prefix(glob: str) -> str:
+ """The fixed leading part of a glob, cut at the last slash before a wildcard."""
+ m = re.search(r'[*?\[]', glob)
+ if not m:
+ return glob
+ return glob[:m.start()].rsplit('/', 1)[0] + '/' if '/' in glob[:m.start()] else ''
+
+
+def may_overlap(a: str, b: str) -> bool:
+ """Conservative: true unless the two globs provably select disjoint files."""
+ pa, pb = literal_prefix(a), literal_prefix(b)
+ return pa.startswith(pb) or pb.startswith(pa)
+
+
+def area_of(path: str, cfg: dict) -> str | None:
+ """The first area owning `path`, or None when it is shared or unknown."""
+ if matches(path, cfg['shared']):
+ return None
+ for name, area in cfg['areas'].items():
+ if matches(path, area['paths']):
+ return name
+ return None
+
+
+def scope(files: list[str], cfg: dict) -> tuple[list[str], set[str] | None]:
+ """Return (changed areas, workflows to ignore). Ignore is None when nothing is."""
+ areas: set[str] = set()
+ for f in files:
+ a = area_of(f, cfg)
+ if a is None:
+ return ['all'], set()
+ areas.add(a)
+ if not files:
+ return ['all'], set()
+ mapped = {w for a in cfg['areas'].values() for w in a['workflows']}
+ needed = {w for name in areas for w in cfg['areas'][name]['workflows']}
+ return sorted(areas), mapped - needed
+
+
+def ignore_regex(ignored: set[str]) -> str:
+ """An anchored regex over workflow file names; empty when nothing is ignored."""
+ if not ignored:
+ return ''
+ return '^(' + '|'.join(re.escape(w) for w in sorted(ignored)) + ')$'
+
+
+def urgent_reference_ok(body: str) -> bool:
+ return bool(URGENT_REFERENCE.search(body or ''))
+
+
+def pr_triggers(workflow: Path) -> list[str] | None:
+ """The `pull_request` path globs of a workflow, or None if it has no path filter."""
+ import yaml
+ on = yaml.safe_load(workflow.read_text()).get(True) or {}
+ if not isinstance(on, dict):
+ return None
+ pr = on.get('pull_request') or {}
+ paths = pr.get('paths') if isinstance(pr, dict) else None
+ if not paths or 'paths-ignore' in pr:
+ return None
+ return [p for p in paths if not p.startswith('!')]
+
+
+def expected_areas(workflow: Path, cfg: dict) -> set[str]:
+ """Every area a workflow's own trigger paths could touch (the superset the map must keep)."""
+ paths = pr_triggers(workflow)
+ if paths is None:
+ return set()
+ return {name for name, area in cfg['areas'].items()
+ if any(may_overlap(p, g) for p in paths for g in area['paths'])}
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser()
+ ap.add_argument('--map', type=Path, default=MAP_PATH)
+ ap.add_argument('--labels', default='')
+ ap.add_argument('--body-file', type=Path)
+ args = ap.parse_args()
+ cfg = load_map(args.map)
+ files = [l.strip() for l in sys.stdin if l.strip()]
+ areas, ignored = scope(files, cfg)
+ regex = ignore_regex(ignored)
+ urgent = 'urgent' in [l.strip() for l in args.labels.split(',')]
+ lines = [
+ f'changed files: {len(files)}',
+ f'areas: {", ".join(areas)}',
+ f'workflows the gate ignores: {", ".join(sorted(ignored)) or "none (waits for every run)"}',
+ ]
+ if urgent:
+ body = args.body_file.read_text() if args.body_file else ''
+ ok = urgent_reference_ok(body)
+ lines.append('urgent lane: ' + ('Linear or incident reference found' if ok else
+ 'MISSING Linear issue or incident reference in the PR description'))
+ if not ok:
+ print('\n'.join(lines))
+ print('::error::The `urgent` label needs a Linear issue key (for example CUA-123) or '
+ 'an incident reference in the PR description.')
+ return 1
+ print('\n'.join(lines))
+ out = os.environ.get('GITHUB_OUTPUT')
+ if out:
+ with open(out, 'a') as fh:
+ fh.write(f'areas={",".join(areas)}\nignore_re={regex}\n')
+ summary = os.environ.get('GITHUB_STEP_SUMMARY')
+ if summary:
+ with open(summary, 'a') as fh:
+ fh.write('### ci-gate scope\n\n' + '\n\n'.join(lines) + '\n')
+ return 0
+
+
+if __name__ == '__main__':
+ sys.exit(main())
diff --git a/.github/scripts/tests/test_ci_gate_scope.py b/.github/scripts/tests/test_ci_gate_scope.py
new file mode 100644
index 0000000000..b27adf6b0f
--- /dev/null
+++ b/.github/scripts/tests/test_ci_gate_scope.py
@@ -0,0 +1,174 @@
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+import ci_gate_scope as scope # noqa: E402
+
+CFG = scope.load_map()
+WORKFLOWS = sorted(scope.WORKFLOWS.glob('*.yml'))
+MAPPED = {w for a in CFG['areas'].values() for w in a['workflows']}
+
+
+def ignored(*files):
+ return scope.scope(list(files), CFG)[1]
+
+
+def test_relay_only_change_waits_on_relay_and_rust_jobs_only():
+ areas, skip = scope.scope(['libs/cua-spacesd/crates/cua-relay/src/mesh.rs'], CFG)
+ assert areas == ['relay']
+ assert not skip & {'ci-cua-relay-image.yml', 'ci-cua-spacesd.yml'}
+ # The slow image, SDK and doctor jobs belong to other areas and do not gate a relay change.
+ assert skip >= {'cd-image-linux.yml', 'e2e-cua-sdk.yml', 'ci-cua-sandbox-doctor.yml',
+ 'ci-cua-oci-spacesd.yml', 'ci-cua-spaces-web.yml', 'ci-cua-spaces-macos.yml'}
+
+
+def test_other_spacesd_change_still_waits_on_the_integration_jobs():
+ skip = ignored('libs/cua-spacesd/crates/cua-spacesd/src/lib.rs')
+ assert not skip & {'cd-image-linux.yml', 'e2e-cua-sdk.yml', 'ci-cua-sandbox-doctor.yml',
+ 'ci-cua-oci-spacesd.yml', 'ci-cua-relay-image.yml'}
+
+
+def test_a_change_in_two_areas_needs_both_areas_jobs():
+ skip = ignored('libs/cua-spacesd/crates/cua-relay/src/mesh.rs', 'docs/content/a.mdx')
+ assert 'ci-check-docs-links.yml' not in skip
+ assert 'ci-cua-relay-image.yml' not in skip
+ assert 'ci-cua-spaces-web.yml' in skip
+
+
+ 'Cargo.lock', 'libs/cua-driver/rust/Cargo.lock', 'README.md', 'package.json',
+ '.github/workflows/ci-gate.yml', '.github/ci-areas.json', 'libs/cua/proto/a.proto',
+ 'libs/cua-driver/rust/crates/cua-driver-core/src/lib.rs',
+ 'libs/cua/crates/cua-proto/src/lib.rs', 'rust-toolchain.toml',
+ 'some/unmapped/dir/file.txt',
+])
+def test_shared_and_unknown_files_wait_on_everything(path):
+ areas, skip = scope.scope(['libs/cua-spacesd/crates/cua-relay/a.rs', path], CFG)
+ assert areas == ['all']
+ assert skip == set()
+
+
+def test_empty_change_list_waits_on_everything():
+ assert scope.scope([], CFG) == (['all'], set())
+
+
+def test_unmapped_workflow_is_never_ignored():
+ # A workflow absent from the map is required for every PR.
+ for files in (['docs/content/a.mdx'], ['apps/cua-spaces-web/x.ts']):
+ assert 'ci-check-emudhra-distrust.yml' not in ignored(*files)
+ assert 'ci-check-emudhra-distrust.yml' not in MAPPED
+
+
[email protected](('glob', 'path', 'hit'), [
+ ('libs/a/**', 'libs/a/b/c.rs', True),
+ ('libs/a/**', 'libs/ab/c.rs', False),
+ ('*', 'README.md', True),
+ ('*', 'docs/README.md', False),
+ ('**/Cargo.lock', 'Cargo.lock', True),
+ ('**/Cargo.lock', 'a/b/Cargo.lock', True),
+ ('libs/*/x.rs', 'libs/a/b/x.rs', False),
+])
+def test_glob_matching(glob, path, hit):
+ assert bool(scope.glob_to_regex(glob).match(path)) is hit
+
+
+def test_every_mapped_workflow_exists_and_every_area_name_is_listed_once():
+ names = {w.name for w in WORKFLOWS}
+ for area in CFG['areas'].values():
+ assert set(area['workflows']) <= names
+ assert len(area['workflows']) == len(set(area['workflows']))
+
+
[email protected]('workflow', WORKFLOWS, ids=lambda w: w.name)
+def test_map_covers_every_area_a_workflow_can_trigger_on(workflow):
+ """The map may only narrow on purpose: a workflow whose own paths reach an area must
+ be listed there, unless the area is marked `narrowed` (then its list is a subset)."""
+ for name in scope.expected_areas(workflow, CFG):
+ area = CFG['areas'][name]
+ if area.get('narrowed'):
+ continue
+ assert workflow.name in area['workflows'], (
+ f'{workflow.name} triggers on paths in area "{name}" but is not listed there; '
+ f'add it to .github/ci-areas.json')
+
+
+def test_the_gate_and_its_scope_files_are_shared():
+ for f in ('.github/workflows/ci-gate.yml', '.github/ci-areas.json',
+ '.github/scripts/ci_gate_scope.py'):
+ assert scope.area_of(f, CFG) is None
+
+
[email protected](('body', 'ok'), [
+ ('Fixes CUA-2338', True),
+ ('Linear: https://linear.app/trycua/issue/CUA-2338/urgent-fix-lane', True),
+ ('Incident #482: relay down', True),
+ ('incident 2026-10-25 relay outage', True),
+ ('urgent please', False),
+ ('', False),
+ (None, False),
+ ('Co-authored by UTF-8 and sha-256', False),
+ ('Linear: CLE-45', True),
+])
+def test_urgent_reference(body, ok):
+ assert scope.urgent_reference_ok(body) is ok
+
+
+def test_urgent_label_without_reference_fails_the_gate(tmp_path):
+ body = tmp_path / 'body.txt'
+ body.write_text('quick fix, no reference')
+ done = subprocess.run(
+ [sys.executable, str(scope.ROOT / '.github/scripts/ci_gate_scope.py'),
+ '--labels', 'bug,urgent', '--body-file', str(body)],
+ input='libs/cua-spacesd/crates/cua-relay/a.rs', capture_output=True, text=True)
+ assert done.returncode == 1
+ assert 'urgent' in done.stdout
+
+
+def test_urgent_label_with_reference_uses_the_same_path_scope(tmp_path):
+ body = tmp_path / 'body.txt'
+ body.write_text('Fixes CUA-2338')
+ out = tmp_path / 'out'
+ done = subprocess.run(
+ [sys.executable, str(scope.ROOT / '.github/scripts/ci_gate_scope.py'),
+ '--labels', 'urgent', '--body-file', str(body)],
+ input='libs/cua-spacesd/crates/cua-relay/a.rs', capture_output=True, text=True,
+ env={**os.environ, 'GITHUB_OUTPUT': str(out)})
+ assert done.returncode == 0, done.stdout
+ assert 'areas=relay' in out.read_text()
+ plain = subprocess.run(
+ [sys.executable, str(scope.ROOT / '.github/scripts/ci_gate_scope.py')],
+ input='libs/cua-spacesd/crates/cua-relay/a.rs', capture_output=True, text=True,
+ env={**os.environ, 'GITHUB_OUTPUT': str(tmp_path / 'out2')})
+ assert (tmp_path / 'out2').read_text() == out.read_text()
+
+
+def test_gate_runs_the_scope_step_first_and_passes_its_output_to_the_wait_step():
+ gate = yaml.safe_load((scope.WORKFLOWS / 'ci-gate.yml').read_text())
+ steps = gate['jobs']['ci-gate']['steps']
+ assert steps[1]['id'] == 'scope'
+ assert steps[2]['env']['IGNORE_RE'] == '${{ steps.scope.outputs.ignore_re }}'
+ assert 'labeled' in gate[True]['pull_request']['types']
+ assert 'edited' in gate[True]['pull_request']['types']
+ assert 'merge_group' in gate[True]
+
+
+def test_gate_run_filter_drops_only_ignored_workflows():
+ script = yaml.safe_load((scope.WORKFLOWS / 'ci-gate.yml').read_text())['jobs']['ci-gate']['steps'][2]['run']
+ jq_filter = next(line.split("='", 1)[1].rsplit("'", 1)[0]
+ for line in script.splitlines() if line.strip().startswith('scope_jq='))
+ runs = [{'path': '.github/workflows/cd-image-linux.yml@refs/pull/1/merge'},
+ {'path': '.github/workflows/ci-cua-spacesd.yml'}]
+ program = f'[.[] | select({jq_filter}) | .path] | length'
+ def count(ignore):
+ return int(subprocess.run(['jq', '-n', '--argjson', 'r', json.dumps(runs), f'$r | {program}'],
+ capture_output=True, text=True,
+ env={**os.environ, 'IGNORE_RE': ignore}).stdout)
+ assert count('') == 2
+ assert count('^(cd-image-linux\\.yml)$') == 1
diff --git a/.github/scripts/tests/test_ci_gate_workflow.py b/.github/scripts/tests/test_ci_gate_workflow.py
index 3d883fd8cd..fb0ee2c7e7 100644
--- a/.github/scripts/tests/test_ci_gate_workflow.py
+++ b/.github/scripts/tests/test_ci_gate_workflow.py
@@ -9,7 +9,8 @@ import yaml
ROOT = Path(__file__).resolve().parents[3]
WORKFLOWS = ROOT / '.github/workflows'
GATE = yaml.safe_load((WORKFLOWS / 'ci-gate.yml').read_text())
-SCRIPT = GATE['jobs']['ci-gate']['steps'][0]['run']
+STEPS = {step.get('name'): step for step in GATE['jobs']['ci-gate']['steps']}
+SCRIPT = STEPS['Wait for every other workflow on the pull request head']['run']
@pytest.mark.parametrize('filename', [
diff --git a/.github/scripts/tests/test_e2e_cua_sdk_scope.py b/.github/scripts/tests/test_e2e_cua_sdk_scope.py
index 93d52faf5f..29e5d893ab 100644
--- a/.github/scripts/tests/test_e2e_cua_sdk_scope.py
+++ b/.github/scripts/tests/test_e2e_cua_sdk_scope.py
@@ -474,7 +474,7 @@ def test_git_writes_github_output(repo, monkeypatch, tmp_path):
# --- ci-gate counts a skipped run as passed ------------------------------------
-GATE_SCRIPT = GATE["jobs"]["ci-gate"]["steps"][0]["run"]
+GATE_SCRIPT = next(s["run"] for s in GATE["jobs"]["ci-gate"]["steps"] if s.get("name", "").startswith("Wait for every other workflow"))
def run_gate(rows, jobs):
diff --git a/.github/workflows/ci-gate.yml b/.github/workflows/ci-gate.yml
index 3a259a02d8..10bce4aa13 100644
--- a/.github/workflows/ci-gate.yml
+++ b/.github/workflows/ci-gate.yml
@@ -16,11 +16,44 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 360
steps:
+ # Which workflows this gate may ignore, from the paths the PR changes (area map:
+ # .github/ci-areas.json, docs/contributing/CI.md). The merge queue entry resolves the
+ # same pull request and reads the same file list, so both events compute one set.
+ # Any failure here fails the gate: nothing is skipped on error.
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+ with:
+ persist-credentials: false
+ sparse-checkout: |
+ .github/ci-areas.json
+ .github/scripts/ci_gate_scope.py
+ sparse-checkout-cone-mode: false
+ - name: Scope the gate to the changed areas
+ id: scope
+ env:
+ GH_TOKEN: ${{ github.token }}
+ PR_NUMBER: ${{ github.event.pull_request.number }}
+ QUEUE_REF: ${{ github.event.merge_group.head_ref }}
+ run: |
+ set -euo pipefail
+ api() { local out; for _ in 1 2 3 4 5 6; do out=$(gh api "$@") && { printf '%s\n' "$out"; return; }; sleep 20; done; return 1; }
+ pr=$PR_NUMBER
+ if [[ -n "$QUEUE_REF" ]]; then
+ [[ "$QUEUE_REF" =~ /pr-([0-9]+) ]] || { echo "::error::cannot read the pull request from $QUEUE_REF"; exit 1; }
+ pr=${BASH_REMATCH[1]}
+ fi
+ api "repos/$GITHUB_REPOSITORY/pulls/$pr" --jq '.body // ""' > "$RUNNER_TEMP/pr-body.txt"
+ labels=$(api "repos/$GITHUB_REPOSITORY/issues/$pr/labels" --jq '[.[].name] | join(",")')
+ api --paginate "repos/$GITHUB_REPOSITORY/pulls/$pr/files?per_page=100" \
+ --jq '.[] | .filename, (.previous_filename // empty)' > "$RUNNER_TEMP/files.txt"
+ # The files API stops at 3000 entries; a PR that large waits on everything.
+ if (( $(wc -l < "$RUNNER_TEMP/files.txt") >= 3000 )); then echo ".github/too-many-files" > "$RUNNER_TEMP/files.txt"; fi
+ python3 .github/scripts/ci_gate_scope.py --labels "$labels" --body-file "$RUNNER_TEMP/pr-body.txt" < "$RUNNER_TEMP/files.txt"
- name: Wait for every other workflow on the pull request head
env:
GH_TOKEN: ${{ github.token }}
PR_SHA: ${{ github.event.pull_request.head.sha }}
QUEUE_REF: ${{ github.event.merge_group.head_ref }}
+ IGNORE_RE: ${{ steps.scope.outputs.ignore_re }}
run: |
set -uo pipefail
api() { local out; for _ in 1 2 3 4 5 6; do out=$(gh api "$@") && { printf '%s\n' "$out"; return; }; sleep 120; done; return 1; }
@@ -30,9 +63,12 @@ jobs:
pr=${BASH_REMATCH[1]}
sha=$(api "repos/$GITHUB_REPOSITORY/pulls/$pr" --jq .head.sha) || exit 1
fi
+ # IGNORE_RE (from the scope step) names workflow files that belong only to areas this PR
+ # did not touch. Empty means wait for every run.
+ scope_jq='(env.IGNORE_RE // "") == "" or ((.path | sub("@.*"; "") | split("/") | last) | test(env.IGNORE_RE) | not)'
runs() {
api --paginate "repos/$GITHUB_REPOSITORY/actions/runs?head_sha=$sha&per_page=100" \
- --jq ".workflow_runs[] | select(.workflow_id != $GITHUB_WORKFLOW_ID and (.event == \"pull_request\" or .event == \"pull_request_target\") and (.path | test(\"claude-auto-fix|ci-release-reminder|review-cua-perception-candidates\") | not)) | [.workflow_id, .id, .name, .conclusion // \"\", .status] | @tsv"
+ --jq ".workflow_runs[] | select(.workflow_id != $GITHUB_WORKFLOW_ID and (.event == \"pull_request\" or .event == \"pull_request_target\") and (.path | test(\"claude-auto-fix|ci-release-reminder|review-cua-perception-candidates\") | not) and ($scope_jq)) | [.workflow_id, .id, .name, .conclusion // \"\", .status] | @tsv"
}
GITHUB_WORKFLOW_ID=$(api "repos/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID" --jq .workflow_id) || exit 1
# Two identical listings cannot prove every run has appeared, so no verdict is allowed
diff --git a/docs/contributing/CI.md b/docs/contributing/CI.md
new file mode 100644
index 0000000000..1e37c4a340
--- /dev/null
+++ b/docs/contributing/CI.md
@@ -0,0 +1,77 @@
+# CI
+
+Every pull request must pass one required check, **CI: gate** (`ci-gate`). The gate waits for the other
+pull request workflows and passes when they pass. This page explains which of those workflows it waits for.
+
+## Path-scoped gate
+
+A workflow still starts on its own `paths:` filter. The gate then waits only for the workflows that belong
+to the areas the pull request changed. Slow jobs for other areas (for example the Linux image build on a
+relay-only change) still run, but they no longer hold up the merge.
+
+The area map is [`.github/ci-areas.json`](../../.github/ci-areas.json). The scope step in
+`.github/workflows/ci-gate.yml` runs [`.github/scripts/ci_gate_scope.py`](../../.github/scripts/ci_gate_scope.py)
+on the pull request's file list.
+
+Rules, in order:
+
+1. A changed file that matches a **shared** glob, or matches no area at all, makes the gate wait for every run, as it did before scoping.
+2. Any other changed file belongs to the first area (top to bottom in the table) whose globs match it.
+3. A workflow listed under an area is required only when one of its areas changed.
+4. A workflow listed under no area (for example the CLA, eMudhra and release-metadata checks) is always required. A new workflow is therefore required until someone maps it.
+
+Merge-queue runs (`merge_group`) read the file list of the same pull request through the same API call, so
+the queue and the pull request wait on the same set. If the scope step fails for any reason, the gate fails.
+It never skips on error.
+
+### Shared files (wait for everything)
+
+`.github/**`, `*`, `**/Cargo.lock`, `**/rust-toolchain.toml`, `**/pnpm-lock.yaml`, `**/pnpm-workspace.yaml`, `**/package-lock.json`, `**/uv.lock`, `libs/cua/Cargo.toml`, `libs/cua-driver/rust/Cargo.toml`, `libs/cua-spacesd/Cargo.toml`, `libs/cua-driver/rust/.cargo/**`, `libs/cua/.cargo/**`, `libs/cua/proto/**`, `libs/cua/crates/cua-proto/**`, `libs/cua-driver/rust/crates/cua-driver-core/**`, `libs/cua-driver/rust/crates/cua-driver-contract/**`, `libs/cua/crates/cua-sandbox-core/**`, `scripts/ci/**`, `flake.nix`, `nix/**`
+
+Any file outside every area below also counts as shared.
+
+### Areas
+
+| Area | Paths | Workflows mapped | Slow jobs that gate it |
+|---|---|---|---|
+| `relay` | `libs/cua-spacesd/crates/cua-relay/**` | 5 (narrowed by hand) | `ci-cua-relay-image`, `ci-cua-spacesd` |
+| `spacesd` | `libs/cua-spacesd/**` | 19 | `cd-image-linux`, `ci-cua-oci-spacesd`, `ci-cua-relay-image`, `ci-cua-sandbox-doctor`, `ci-cua-sdk`, `ci-cua-spacesd`, `ci-openkoalabot-example-tauri`, `ci-test-python`, `e2e-cua-sdk` |
+| `driver-rust` | `libs/cua-driver/rust/**` | 30 | `ci-check-docs`, `ci-cua-sandbox-doctor`, `ci-cua-spacesd`, `ci-rust-linux`, `ci-rust-macos`, `ci-rust-windows`, `e2e-cua-sdk`, `e2e-rust-linux` |
+| `driver` | `libs/cua-driver/**`, `libs/cua-driver-bench/**` | 35 | `ci-check-docs`, `ci-cua-sandbox-doctor`, `ci-cua-spacesd`, `ci-rust-linux`, `ci-rust-macos`, `ci-rust-windows`, `e2e-cua-sdk`, `e2e-rust-linux` |
+| `cua` | `libs/cua/**`, `tests/e2e/**` | 44 | `cd-image-linux`, `ci-check-docs`, `ci-cua-oci-spacesd`, `ci-cua-relay-image`, `ci-cua-sandbox-doctor`, `ci-cua-sdk`, `ci-cua-spaces-macos`, `ci-cua-spaces-web`, `ci-cua-spaces`, `ci-cua-spacesd`, `ci-openkoalabot-example-tauri`, `ci-test-python`, `e2b-bindings`, `e2e-cua-sdk` |
+| `images` | `libs/images/**`, `scripts/images/**` | 19 | `cd-image-linux`, `ci-check-docs`, `ci-cua-spaces-macos`, `ci-cua-spacesd`, `e2e-cua-sdk` |
+| `spaces-web` | `apps/cua-spaces-web/**`, `apps/cua-spaces-desktop/**` | 7 | `ci-cua-spaces-macos`, `ci-cua-spaces-web` |
+| `spaces-app` | `apps/cua-spaces/**` | 7 | `ci-cua-spaces-web`, `ci-cua-spaces` |
+| `spaces-macos` | `apps/cua-spaces-macos/**` | 7 | `ci-cua-spaces-macos`, `ci-cua-spaces-web` |
+| `python` | `libs/python/**`, `libs/cua-bench/**`, `libs/cua-bench-rl/**`, `libs/cua-s1/**` | 24 | `ci-check-docs`, `ci-cua-sdk`, `ci-test-python`, `e2e-cua-sdk` |
+| `typescript` | `libs/typescript/**`, `libs/cuabot/**` | 9 | none of the slow jobs |
+| `lume` | `libs/lume/**`, `libs/lumier/**`, `libs/spaces-sdk-swift/**` | 11 | `ci-check-docs`, `ci-cua-sdk`, `ci-cua-spaces-macos`, `ci-swift-lume` |
+| `containers` | `libs/kasm/**`, `libs/qemu-docker/**`, `libs/xfce/**`, `libs/xfce-cua/**` | 11 | none of the slow jobs |
+| `docs` | `docs/**`, `skills/**` | 17 | `ci-check-docs`, `e2e-cua-sdk` |
+| `compat` | `tests/compat/**` | 11 | none of the slow jobs |
+| `installers` | `scripts/install/**` | 6 | none of the slow jobs |
+| `examples` | `examples/**` | 5 | `ci-openkoalabot-example-tauri` |
+
+The `relay` area is narrowed by hand: the relay is a standalone server, so a change under
+`libs/cua-spacesd/crates/cua-relay/` waits for `ci-cua-relay-image`, `ci-cua-spacesd` (the Rust workspace
+build, lint and tests) and the cheap repo checks, and not for the Linux image, SDK end-to-end, image doctor or OCI jobs.
+Every other area lists every workflow whose own `paths:` reach it.
+
+### Keeping the map correct
+
+`.github/scripts/tests/test_ci_gate_scope.py` (run by `CI: Test Scripts`) fails when a workflow's
+`pull_request` paths reach an area that does not list it. When you add a workflow with a `paths:` filter,
+or add a path to one, add it to the matching areas in `.github/ci-areas.json`. Changing the map or the gate
+is a `.github/**` change, so it waits for every workflow.
+
+## Urgent-fix lane
+
+Label a pull request `urgent` for a production fix that cannot wait for the full suite:
+
+- The gate still scopes to the changed areas (the same logic as above). The lane skips nothing else.
+- The pull request description must reference a Linear issue (`CUA-123`, `CLE-45` or a Linear issue URL) or an
+ incident (`Incident #482`, `incident 2026-10-25 relay outage`). The gate fails the pull request without one,
+ so it blocks the merge. Edit the description to fix it; the gate re-runs on `edited`.
+- `trycua/cua` has no merge queue, so an urgent pull request merges with `gh pr merge --auto --squash` as soon
+ as its scoped gate is green. Nothing is waiting in front of it.
+- Do not use the lane to skip a failing check. A failing required check still blocks the merge.
diff --git a/docs/contributing/TESTING.md b/docs/contributing/TESTING.md
index 3620f8256a..dbfb50c824 100644
--- a/docs/contributing/TESTING.md
+++ b/docs/contributing/TESTING.md
@@ -194,6 +194,9 @@ listed by `pnpm docs:list`); `pnpm docs:check` is the explicit full audit. See
## Before Opening a Pull Request
+The required `ci-gate` check waits only for the workflows of the areas your pull request changes; see
+[CI](CI.md) for the area map and the `urgent` label.
+
1. Run focused tests while developing.
2. Run the complete deterministic test owner for every component changed.
3. Run the affected interactive E2E lane when desktop behavior or its contract changes.