CI/CD, Release, and Infrastructure

This section provides an overview of the automated pipelines and infrastructure tooling that power the Executor monorepo. The system is designed to maintain high quality through sharded testing, provide ephemeral preview environments for Cloudflare Workers, and manage a complex multi-target release process spanning NPM, GitHub, and Docker.

The infrastructure utilizes GitHub Actions running on Blacksmith runners .github/workflows/ci.yml16 Turbo for task orchestration turbo.json1-29 and Changesets for version management .changeset/config.json1-42

CI/CD System Overview

The following diagram illustrates the relationship between code entities and the CI/CD pipeline stages.

CI/CD Pipeline to Code Entity Mapping

Sources: .github/workflows/ci.yml1-12 .github/workflows/release.yml1-7 .github/workflows/publish-executor-package.yml1-9 scripts/validate-release-ref.ts1-10 .changeset/config.json1-5

CI Pipeline and Quality Gates

The CI workflow is the primary gatekeeper for the main branch. It utilizes path filtering to optimize runner usage and executes a comprehensive suite of tests across different host environments.

• Path Filtering: Uses dorny/paths-filter to determine if specific smoke tests (Desktop or Self-host Docker) need to run based on changed files .github/workflows/ci.yml24-56
• Task Orchestration: Turbo manages build, test, and typecheck tasks, utilizing remote caching to speed up execution turbo.json6-22
• Quality Gates: Includes linting via oxlint, formatting checks, and strict type checking using Node 24 and Bun 1.3.11 .github/workflows/ci.yml58-138
• E2E Sharding: End-to-end tests are sharded (e.g., 4 shards for the Cloud target) to maintain a sub-30 minute execution time .github/workflows/ci.yml176-191

For details, see CI Pipeline and Quality Gates.

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

Release Process

Executor follows a tag-driven release lifecycle orchestrated by Changesets. The process manages three distinct publish paths: the CLI (executor NPM package), library packages (@executor-js/*), and the self-host Docker image.

• Versioning: Triggered by merging a "Version Packages" PR created by the Changesets action .github/workflows/release.yml51-70
• Tag Validation: The validate-release-ref.ts script ensures that tags match the versions defined in apps/cli/package.json scripts/validate-release-ref.ts1-20
• Multi-Target Build:
  • NPM: Publishes libraries and the CLI wrapper using trusted publishing .github/workflows/publish-executor-package.yml63-81
  • Desktop: Builds an Electron matrix for macOS (arm64/x64), Windows, and Linux, bundling the compiled CLI sidecar .github/workflows/publish-desktop.yml30-55
  • Docker: Builds multi-arch (amd64/arm64) images for GHCR .github/workflows/publish-selfhost-docker.yml100-109

For details, see Release Process.

Sources: .github/workflows/release.yml1-137 .github/workflows/publish-executor-package.yml1-92 RELEASING.md1-122 apps/cli/src/release.ts1-193

Preview Environments and E2E Infrastructure

The monorepo supports ephemeral infrastructure for testing Cloudflare-based deployments and providing preview links for pull requests.

• Cloudflare Previews: Every PR against the main repository triggers a deployment of a dedicated stack including a Worker, D1 database, R2 bucket, and Cloudflare Access configuration .github/workflows/preview.yml3-16
• Preview CLI: Managed by apps/host-cloudflare/scripts/preview.ts, which handles the deploy and teardown lifecycle apps/host-cloudflare/scripts/preview.ts1-50
• E2E Infrastructure: Supports testing against multiple targets (cloud, selfhost, local). The system manages port allocation and uses Playwright for browser-based verification .github/workflows/ci.yml176-225
• Binary Previews: pkg.pr.new is used to publish continuous integration snapshots of NPM packages for testing without a full release .github/workflows/pkg-pr-new.yml1-153

Infrastructure to Code Entity Mapping

For details, see Preview Environments and E2E Infrastructure.

Sources: .github/workflows/preview.yml1-133 .github/workflows/pkg-pr-new.yml1-153 apps/host-cloudflare/scripts/preview.ts1-63