CI Pipeline and Quality Gates

Relevant source files

• .github/workflows/ci.yml
• .github/workflows/pkg-pr-new.yml
• .github/workflows/preview-sweep.yml
• .github/workflows/preview.yml
• .github/workflows/publish-desktop.yml
• .github/workflows/publish-executor-package.yml
• .github/workflows/publish-selfhost-docker.yml
• .github/workflows/release.yml
• .oxfmtrc.json
• .oxlintrc.jsonc
• apps/host-cloudflare/.gitignore
• apps/host-cloudflare/scripts/preview.ts
• e2e/src/vm/tart.ts
• e2e/targets/desktop.ts
• e2e/targets/registry.ts
• e2e/vitest.config.ts
• packages/core/sdk/src/oxlint-plugin-executor.test.ts
• packages/react/src/lib/auth-placements.tsx
• scripts/oxlint-plugin-executor.js
• scripts/validate-release-ref.ts
• tests/release-workflows.test.ts
• turbo.json

The Executor monorepo utilizes a high-performance CI/CD pipeline designed to maintain strict quality gates across multiple host environments (Cloud, Desktop, CLI, and Self-host). The pipeline leverages Turbo for task orchestration, Blacksmith for optimized runner infrastructure, and a custom oxlint plugin to enforce architectural constraints.

CI Workflow Architecture

The primary CI workflow is defined in .github/workflows/ci.yml. It uses path filtering to optimize execution time, ensuring that expensive smoke tests only run when relevant code changes occur.

Path Filtering and Optimization

The changes job determines which downstream smoke tests are required based on modified files .github/workflows/ci.yml14-57

• desktop_smoke: Triggered by changes in apps/desktop, apps/local, apps/cli, or core packages .github/workflows/ci.yml30-43
• selfhost_docker_smoke: Triggered by changes in apps/host-selfhost or core packages .github/workflows/ci.yml44-56

Task Orchestration

Turbo is used to manage dependencies between tasks and provide remote caching turbo.json1-29

• Concurrency: CI sets TURBO_TEST_CONCURRENCY: 4 to match the Blacksmith 4 vCPU runners .github/workflows/ci.yml149
• Caching: Remote caching is enabled via TURBO_TOKEN and TURBO_TEAM secrets .github/workflows/ci.yml145-148

Pipeline Stages

Job	Purpose	Implementation
Format	Ensures code style compliance.	bun run format:check using oxfmt .github/workflows/ci.yml79
Lint	Enforces static analysis rules.	bun run lint using oxlint with custom rules .github/workflows/ci.yml102
Typecheck	Validates TypeScript integrity.	bun run typecheck across the monorepo .github/workflows/ci.yml137
Test	Runs unit and integration tests.	bun run test .github/workflows/ci.yml174
E2E	Executes sharded browser-based tests.	Vitest + Playwright against cloud and selfhost targets .github/workflows/ci.yml176-190

Sources: .github/workflows/ci.yml1-230 turbo.json1-29

---

Sharded E2E Testing

The E2E suite is sharded to reduce wall-clock time on CI. The cloud target is split into four shards, each booting a fresh dev stack .github/workflows/ci.yml181-188

Vitest Project Configuration

The E2E harness in e2e/vitest.config.ts defines projects for different execution environments:

• cloud: Runs with fileParallelism: false because the internal PGlite socket server is single-connection e2e/vitest.config.ts25
• selfhost-docker: Tests the production Docker artifact using bun serve.ts and /data volumes e2e/vitest.config.ts37-40
• desktop-packaged: The only target that exercises the ensureSupervisedConnection path and the bundled executor sidecar e2e/vitest.config.ts74-79

Data Flow: E2E Execution

1. Global Setup: The globalSetup script (e.g., setup/cloud.globalsetup.ts) boots the target host or attaches to a provided E2E_TARGET_URL e2e/vitest.config.ts12
2. Identity Isolation: Scenarios are isolated by creating fresh identities rather than database resets e2e/vitest.config.ts6
3. Target Selection: The E2E_TARGET environment variable dictates which host implementation the scenario interacts with e2e/vitest.config.ts11

Sources: e2e/vitest.config.ts1-132 .github/workflows/ci.yml176-230

---

Custom Quality Gates: oxlint-plugin-executor

To maintain architectural purity and prevent common pitfalls with the Effect runtime, the codebase employs a custom oxlint plugin defined in scripts/oxlint-plugin-executor.js.

Key Custom Rules

• Architectural Constraints:
  • no-cross-package-relative-imports: Prevents bypassing package boundaries .oxlintrc.jsonc9
  • no-direct-cloud-executor-schema-import: Restricts access to internal cloud schemas .oxlintrc.jsonc10
• Effect Runtime Safety:
  • no-try-catch-or-throw: Forces the use of Effect's error handling patterns .oxlintrc.jsonc30
  • no-promise-reject / no-promise-catch: Discourages standard Promise error handling in favor of Effect .oxlintrc.jsonc21-22
  • prefer-yield-tagged-error: Ensures errors are correctly yielded within generators .oxlintrc.jsonc36
• UI Consistency:
  • react/forbid-elements: Blocks raw HTML elements like button or input, requiring the use of themed components from @executor/react .oxlintrc.jsonc37-58

Rule Overrides

Strict rules are relaxed for specific boundaries, such as the CLI (apps/cli) and E2E harness (e2e/), where raw Promise handling or standard Error constructors are necessary for interoperability with external drivers (e.g., Playwright, PTY) .oxlintrc.jsonc60-103

Sources: .oxlintrc.jsonc1-167 scripts/oxlint-plugin-executor.js1-78

---

Release and Smoke Testing

Releases are tag-driven and involve multiple specialized smoke tests to ensure binary and container integrity.

Desktop Smoke Test

The publish-desktop.yml workflow gates releases on the test:smoke task .github/workflows/publish-desktop.yml110-113 This ensures the compiled CLI sidecar boots correctly and can resolve its internal native bindings (like libsql), which standard bun run might mask due to local node_modules resolution .github/workflows/publish-desktop.yml106-109

Self-host Docker Smoke Test

The CI workflow includes a selfhost_docker_smoke job that builds the Docker image using the apps/host-selfhost/Dockerfile and runs E2E scenarios against it .github/workflows/ci.yml232-265

Infrastructure: Blacksmith and R2

• Blacksmith: Custom Ubuntu runners (4 vCPU) are used for high-performance builds and Docker image generation .github/workflows/publish-selfhost-docker.yml21
• R2 Storage: Preview binaries for PRs are uploaded to Cloudflare R2 using curl --aws-sigv4 for S3-compatible authentication .github/workflows/pkg-pr-new.yml65-82

Release Validation Logic

The scripts/validate-release-ref.ts utility is used across all publish workflows to ensure that the Git tag, package version, and environment variables are synchronized before any artifacts are pushed to NPM or GHCR .github/workflows/publish-executor-package.yml44-47

Sources: .github/workflows/publish-desktop.yml1-187 .github/workflows/publish-selfhost-docker.yml1-226 .github/workflows/pkg-pr-new.yml1-153

---

System Integration Diagrams

CI Pipeline Data Flow

This diagram maps the flow from code change to quality gate validation.

Sources: .github/workflows/ci.yml14-57 .oxlintrc.jsonc1-3 e2e/vitest.config.ts1-20

Release and Artifact Promotion

This diagram illustrates how a validated tag triggers the multi-platform artifact generation.

Sources: .github/workflows/publish-executor-package.yml83-92 .github/workflows/publish-desktop.yml100-105 .github/workflows/publish-selfhost-docker.yml133-142