Skip to main content

​
Workflows

CI runs on CircleCI with three workflows across two separate config files.
ConfigTriggerWorkflows
.circleci/development.ymlPushesci
.circleci/release.ymlTagsrelease + release-cli
WorkflowTrigger FilterPurpose
ciAny branch including mainLint, typecheck, test (PRs); plus changesets and tag-release (main)
releaseTags: @agent-facets/*@*Library package publish to npm
release-cliTags: agent-facets@*CLI matrix publish to npm

​
CI workflow

The ci workflow has two jobs that run on different branches, check and main-pipeline.

​
check (PR branches)

Runs on every push to branches except main. We use Turborepo for caching and incremental builds.
1
Load artifacts from remote cache
2
Validate via bun check with remote caching
3
Save artifacts to remote turbo cache

​
main-pipeline (main only)

Runs on pushes to main only. Executes three steps sequentially in a single job:
1

Check

Run bun check with caching (same as PR branches)
2

Changesets

bun scripts/release/version.ts (consume changesets, open/update version PR)
3

Tag Release

bun scripts/release/tag.ts (create version tags for unpublished packages)
4
Sends maintainer notification on failure

​
Release workflows

Triggered explicitly via CircleCI API v2 by scripts/release/tag.ts after pushing tags (see Release Pipeline for why we don’t rely on tag-push webhooks). The tag pattern determines which workflow within the release pipeline runs.

​
release (library packages)

Triggered by scoped tags matching @agent-facets/*@<version>. Each tag publishes one library package.
1
Parses the package name and version from the tag
2
Skips private packages
3
Builds via turbo
4
Publishes the package to npm
5
Creates a GitHub Release
6
Sends maintainer notification

​
release-cli (CLI)

Triggered by unscoped tags matching agent-facets@<version>. Uses a three-stage matrix pipeline.
1

Build CLI

Cross-compiles all 12 platform binaries, persists build output to workspace
2

Publish Platform Packages 12 total

Each matrix instance publishes one platform binary directly to latest in its own executor
3

Finalize CLI

1
Publishes the CLI package to latest
2
Verifies all 13 packages are visible on npm
3
Creates a GitHub Release
4
Sends maintainer notification
Both workflows send failure notifications via the notify-failure reusable command.

​
Notifications

  1. Failure notifications – any release workflow failure notifies maintainers
  2. Success notifications – when any package successfully publishes to npm

​
Contexts

CircleCI contexts provide environment variables to jobs.
ContextVariablesUsed by
turbo-cacheTurborepo remote cache credentialscheck, main-pipeline, all release jobs
bot-contextnpm OIDC config, GitHub app credentials, CircleCI API tokenmain-pipeline, all release jobs
slack-secretsNotification webhook credentialsmain-pipeline, all release jobs
bot-context includes CIRCLECI_API_TOKEN (a personal API token with write access to the project), which scripts/release/tag.ts uses to explicitly trigger release pipelines via the CircleCI v2 API. See Release Pipeline troubleshooting for rotation steps.

​
Config source structure

CircleCI configs are authored as modular YAML files under source directories. Running bun ci:pack will compile them into single files for CircleCI to consume.
.circleci
development CI
commands
jobs
workflows
@config.yml
release CD
commands contents are symlinks to ../development/commands/*
jobs
workflows
@config.yml
development.yml packed CI config (generated)
release.yml packed CD config (generated)
Commands in release/commands/ are symlinks to development/commands/This is because the CircleCI config pack tool does not support imports or other forms of code sharing.

​
Modifying CI

1

Edit source files

Edit files under .circleci/development/ or .circleci/release/.
2

Regenerate packed configs

bun run ci:pack
This runs circleci config pack on both source directories.
3

Commit & Verify

Commit the changes and verify that the CircleCI config works in your PR