OpenClaw CI 파이프라인 최적화: 빌드 시간 단축 가이드

반복되는 CI 실패와 긴 대기 시간 때문에 개발 흐름이 끊겨 답답했던 적 있으신가요? 효율적인 파이프라인은 개발자의 생산성을 결정짓는 핵심 요소입니다.

OpenClaw는 CI 파이프라인 최적화를 통해 불필요한 작업을 줄이고, 변경 사항에 최적화된 테스트만 실행하여 개발 속도를 높여줍니다.

작업 개요 (Job Overview)

아래 표는 각 작업의 목적과 실행 조건을 정리한 내용입니다.

작업 (Job)	목적	실행 조건
preflight	문서 변경, 변경된 범위, 확장 기능 감지 및 CI 매니페스트 빌드	드래프트가 아닌 푸시 및 PR 발생 시 항상
security-scm-fast	zizmor를 통한 개인 키 탐지 및 워크플로우 감사	드래프트가 아닌 푸시 및 PR 발생 시 항상
security-dependency-audit	npm 권고 사항에 대한 의존성 없는 프로덕션 락파일 감사	드래프트가 아닌 푸시 및 PR 발생 시 항상
security-fast	빠른 보안 작업을 위한 필수 집계	드래프트가 아닌 푸시 및 PR 발생 시 항상
build-artifacts	dist/ 및 Control UI 빌드, 하위 작업을 위한 아티팩트 업로드	Node.js 관련 변경 시
checks-fast-core	번들/플러그인 계약/프로토콜 검사 등 빠른 Linux 정확성 확인	Node.js 관련 변경 시
checks-fast-contracts-channels	안정적인 집계 결과를 갖춘 샤딩된 채널 계약 검사	Node.js 관련 변경 시
checks-node-extensions	확장 기능 제품군 전반의 전체 번들 플러그인 테스트 샤드	Node.js 관련 변경 시
checks-node-core-test	채널, 번들, 계약 및 확장 기능을 제외한 핵심 Node.js 테스트 샤드	Node.js 관련 변경 시
extension-fast	변경된 번들 플러그인에 집중된 테스트	확장 기능 변경 감지 시
check	프로덕션 타입, 린트, 가드, 테스트 타입 및 엄격한 스모크 테스트	Node.js 관련 변경 시
check-additional	아키텍처, 경계, 확장 표면 가드, 패키지 경계 및 Gateway 워치 샤드	Node.js 관련 변경 시
build-smoke	빌드된 CLI 스모크 테스트 및 시작 메모리 스모크 테스트	Node.js 관련 변경 시
checks	나머지 Linux Node.js 레인: 채널 테스트 및 푸시 전용 Node.js 22 호환성	Node.js 관련 변경 시
check-docs	문서 포맷팅, 린트 및 깨진 링크 검사	문서 변경 시
skills-python	Python 기반 스킬을 위한 Ruff 및 pytest	Python 스킬 관련 변경 시
checks-windows	Windows 전용 테스트 레인	Windows 관련 변경 시
macos-node	공유 빌드 아티팩트를 사용하는 macOS TypeScript 테스트 레인	macOS 관련 변경 시
macos-swift	macOS 앱을 위한 Swift 린트, 빌드 및 테스트	macOS 관련 변경 시
android	Android 빌드 및 테스트 매트릭스	Android 관련 변경 시

빠른 실패 순서 (Fail-Fast Order)

비용이 많이 드는 작업 전에 저렴한 검사를 먼저 수행하여 전체적인 CI 시간을 단축합니다.

1. preflight 작업이 어떤 레인이 존재할지 결정합니다. docs-scope 및 changed-scope 로직은 독립적인 작업이 아닌 이 작업 내부의 단계로 실행됩니다.
2. security-scm-fast, security-dependency-audit, security-fast, check, check-additional, check-docs 및 skills-python은 무거운 아티팩트나 플랫폼 매트릭스 작업을 기다리지 않고 빠르게 실패를 보고합니다.
3. build-artifacts는 빠른 Linux 레인과 병렬로 실행되어 공유 빌드가 준비되는 즉시 하위 소비자가 작업을 시작할 수 있게 합니다.
4. 이후 더 무거운 플랫폼 및 런타임 레인이 확장됩니다: checks-fast-core, checks-fast-contracts-channels, checks-node-extensions, checks-node-core-test, extension-fast, checks, checks-windows, macos-node, macos-swift, android.

범위 로직은 scripts/ci-changed-scope.mjs에 있으며 src/scripts/ci-changed-scope.test.ts의 단위 테스트로 커버됩니다. 별도의 install-smoke 워크플로우는 자체 preflight 작업을 통해 동일한 범위 스크립트를 재사용합니다. 이는 run_install_smoke를 계산하여 Docker 및 설치 스모크 테스트가 설치, 패키징, 컨테이너 관련 변경 사항에 대해서만 실행되도록 합니다.

로컬 변경 레인 로직은 scripts/changed-lanes.mjs에 있으며 scripts/check-changed.mjs에 의해 실행됩니다. 이 로컬 게이트는 CI 플랫폼 범위보다 아키텍처 경계에 대해 더 엄격합니다. 핵심 프로덕션 변경 시 핵심 프로덕션 타입 체크와 핵심 테스트가 실행되며, 테스트 전용 변경 시에는 테스트 타입 체크와 테스트만 실행됩니다. 공개 플러그인 SDK나 플러그인 계약 변경은 확장 기능이 핵심 계약에 의존하므로 확장 기능 검증까지 확장됩니다. 알 수 없는 루트/설정 변경은 모든 레인을 실행하는 안전한 방식을 택합니다.

푸시 시 checks 매트릭스는 푸시 전용 compat-node22 레인을 추가합니다. PR에서는 이 레인이 건너뛰어지고 매트릭스는 일반 테스트/채널 레인에 집중합니다.

가장 느린 Node.js 테스트 제품군은 포함 파일 샤드로 분할되어 각 작업의 크기를 작게 유지합니다. 채널 계약은 레지스트리와 핵심 커버리지를 각각 8개의 가중치 샤드로 분할하고, 자동 응답 명령 테스트는 4개의 포함 패턴 샤드로, 기타 자동 응답 접두사 그룹은 각각 2개의 샤드로 분할합니다. check-additional 또한 패키지 경계 컴파일/카나리 작업과 런타임 토폴로지 Gateway/아키텍처 작업을 분리합니다.

GitHub는 동일한 PR이나 main 참조에 새로운 푸시가 들어오면 이전 작업을 cancelled로 표시할 수 있습니다. 동일한 참조에 대한 최신 실행도 실패하지 않는 한 이를 CI 노이즈로 간주하세요. 집계 샤드 검사는 이 취소 사례를 명시적으로 호출하여 테스트 실패와 쉽게 구분할 수 있도록 합니다.

실행 환경 (Runners)

각 작업은 적절한 환경에서 실행되어 최적의 성능을 보장합니다.

러너 (Runner)	작업 (Jobs)
blacksmith-16vcpu-ubuntu-2404	preflight, security-scm-fast, security-dependency-audit, security-fast, build-artifacts, Linux checks, docs checks, Python skills, android
blacksmith-32vcpu-windows-2025	checks-windows
macos-latest	macos-node, macos-swift

로컬 환경 대응 (Local Equivalents)

CI에서 실행되는 로직을 로컬에서도 동일하게 검증할 수 있습니다.

pnpm changed:lanes   # inspect the local changed-lane classifier for origin/main...HEAD
pnpm check:changed   # smart local gate: changed typecheck/lint/tests by boundary lane
pnpm check          # fast local gate: production 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:channels
pnpm test:contracts:channels
pnpm check:docs     # docs format + lint + broken links
pnpm build          # build dist when CI artifact/build-smoke lanes matter

다음 단계

더 자세한 설정이나 도움이 필요하시면 AI Setup Assistant를 확인해 보세요.

관련 문서

• CI Pipeline 가이드
• 로컬 개발 환경 설정