The Executor release lifecycle is a tag-driven process coordinated by Changesets and GitHub Actions. It manages the versioning and distribution of three primary artifacts: the executor CLI (NPM and binary), the @executor-js/* library packages, and the self-hosted Docker image.
The release process follows a strictly ordered sequence to ensure that binary dependencies (like the CLI sidecar) are available before downstream applications (like Desktop or Docker) are built.
.changeset/*.md files to PRs.release.yml workflow uses changesets/action to consolidate these into a "Version Packages" PR RELEASING.MD10-14v* tag RELEASING.MD19-20This diagram illustrates the dependencies between the various release workflows.
Sources: .github/workflows/release.yml51-61 .github/workflows/publish-executor-package.yml83-92 RELEASING.MD8-31
Executor uses @changesets/cli to manage semantic versioning.
bun run release:beta:start, which creates a .changeset/pre.json file to route versions to the beta NPM tag RELEASING.MD32-46scripts/validate-release-ref.ts script ensures that the tag being published matches the version defined in apps/cli/package.json to prevent accidental tag-version mismatches .github/workflows/publish-executor-package.yml44-47Sources: .changeset/config.json1-42 RELEASING.MD32-46 scripts/validate-release-ref.ts1-100
The CLI is a self-contained binary built using bun build --compile. Because Bun's compiler cannot bundle native .node modules or certain WASM files into the virtual filesystem (bunfs), the build script apps/cli/src/build.ts performs manual asset staging.
The build.ts script handles:
@napi-rs/keyring and libsql native modules next to the binary apps/cli/src/build.ts127-180quickjs-wasmfile and 1password-sdk-core WASM files apps/cli/src/build.ts15-34linux-x64, linux-arm64 (including musl variants), darwin-x64/arm64, and win32-x64/arm64 apps/cli/src/build.ts66-75Sources: apps/cli/src/build.ts60-125 apps/cli/src/build.ts127-180
The Desktop application release is triggered by the CLI release. It uses a matrix strategy to build on native runners (macOS, Windows, Ubuntu) to support signing and notarization.
apps/desktop/scripts/build-sidecar.ts invokes the CLI build and copies the resulting binary into resources/executor/ apps/desktop/scripts/build-sidecar.ts43-46apps/desktop/scripts/smoke-sidecar.ts executes the bundled binary to verify it can boot and handle MCP requests apps/desktop/scripts/smoke-sidecar.ts8-18APPLE_API_KEY for notarytool upload and CSC_LINK for code signing .github/workflows/publish-desktop.yml124-150latest-mac.yml files which are merged in the final release step to support electron-updater .github/workflows/publish-desktop.yml159-162Sources: .github/workflows/publish-desktop.yml25-56 apps/desktop/scripts/build-sidecar.ts1-57 apps/desktop/scripts/smoke-sidecar.ts1-18
To prevent regressions in the compiled environment (which often differ from dev-mode behavior due to bunfs isolation), the release pipeline includes specific smoke tests.
The tests/release-bootstrap-smoke.test.ts simulates a production NPM installation layout. It verifies:
optionalDependencies tests/release-bootstrap-smoke.test.ts106-114libsql) are correctly loaded at runtime tests/release-bootstrap-smoke.test.ts129-131scripts/validate-release-ref.ts acts as a gatekeeper. It is used in every release workflow to:
package.json.vX.Y.Z format.Sources: tests/release-bootstrap-smoke.test.ts98-137 .github/workflows/publish-executor-package.yml44-47 scripts/validate-release-ref.ts1-50
The release process utilizes NPM Trusted Publishing (OIDC).
publish job in .github/workflows/publish-executor-package.yml requests an id-token: write permission .github/workflows/publish-executor-package.yml30NPM_TOKEN secret, using GitHub's identity to authenticate directly with the NPM registry RELEASING.MD107-109Sources: .github/workflows/publish-executor-package.yml25-31 RELEASING.MD107-109
Refresh this wiki