Skip to content

Canopy Pipelines

Canopy Pipelines lets you describe your build and deploy logic in a real .ts file instead of a YAML dialect. @canopy/ci provides the authoring API and the IR (the Canopy Pipeline Graph, or CPG) it compiles to - functions, types, and imports, not a new language.

Availability. The host.pipeline_graph capability is GA, public, and enabled by default. Teams can disable it; when disabled, its API and pipeline-build behavior are unavailable. The graph and pipeline management HTTP routes are still marked preview (unstable) in the API implementation, so their contract may change. host.pipeline_native_deploy is an internal capability that controls repository builds through the graph engine; it is not a customer setting. When enabled, a repository with a canopy.pipeline.ts gets it compiled into a CPG on a build, and a failing required step stops the deploy, leaving the previous release untouched.

Terminal window
bun add @canopy/ci
# or: npm install @canopy/ci

Published on Canopy’s own npm-compatible registry (see Package Registry) and installable anonymously, no Canopy account required just to pull the package.

Add a canopy.pipeline.ts file at your environment’s build path:

canopy.pipeline.ts
import { definePipeline } from '@canopy/ci';
export default definePipeline(({ step, when, canopy }) => {
const src = step.source();
const build = step('build', {
image: 'oven/bun:1-alpine@sha256:5acc90a93e91ff07bf72aa90a7c9f0fa189765aec90b47bdbf2152d2196383c0',
run: 'bun install --frozen-lockfile && bun run build',
inputs: [src],
egress: ['registry.npmjs.org'],
});
const test = step('test', {
image: 'oven/bun:1-alpine@sha256:5acc90a93e91ff07bf72aa90a7c9f0fa189765aec90b47bdbf2152d2196383c0',
run: 'bun test',
inputs: [build],
});
when.branch('main').then(() => {
canopy.environment('<your-environment-id>').deploy({ inputs: [test] });
});
});

Your file is never run to do the work - it’s run once, hermetically (frozen clock, no randomness, no network), to describe the work. That run produces a plain CpgGraph: a set of steps and their dependencies. Canopy schedules, caches, and executes that graph separately - the same separation a build tool like Bazel or Buck makes between defining a build and running one.

when.branch('main').then(...) runs its callback immediately, at compile time, if the predicate matches the real commit/ref this run is for - never deferred, never re-evaluated later. A graph compiled for a feature branch simply has no deploy node in it, not a skipped one. Other matchers: when.tag(pattern), when.event(name), when.pullRequest(), and when.untrustedPullRequest({ acknowledgeRisk: true }) for the one sanctioned way to let a fork-PR run reach a real secret or a deploy at all (policy-gated, rendered clearly in a plan diff).

A step can say it may fail without failing the build:

const gpu = step('gpu-check', { native: { platform: 'darwin/arm64', unavailable: 'fail' }, run: 'sh gpu.sh', optional: true });
step('gpu-report', { image: PYTHON, run: 'python report.py', inputs: [gpu], optional: true });

When an optional step fails, only the steps that depend on it are skipped. Nothing else is cancelled, the build and the deploy go on, and the failed step shows red on the graph page and in canopy pipelines status. The run completes as succeeded, and its pipeline.run_completed event lists the failed optional steps in optional_failed.

Every step that depends on an optional step, by inputs or orderOnlyInputs, must be optional too; Canopy refuses the graph otherwise, because a required step would be skipped without anyone being told. The image Canopy builds from your repository never waits for an optional step. An optional step still runs to its end before the build finishes, so pair one that needs a machine that may be away with unavailable: 'fail' (see Native machines) rather than letting it wait.

optional needs @canopy/ci 0.23 or later.

Host adds a build_image step to a pipeline that declares none, because most pipelines end in an application image. A pipeline that only runs checks or compute jobs says so with the second argument of definePipeline:

export default definePipeline(({ step }) => {
// ...
}, { buildsImage: false });

Host then adds no image step, so a directory without a Dockerfile no longer starts a buildpack fallback. The setting is part of the graph’s identity.

An environment builds from one directory (its build path), but a monorepo pipeline often reads more: a shared SDK, a script, the committed API baselines. Name those once, with the second argument of definePipeline:

export default definePipeline(({ step }) => {
// ...
}, { watch: ['sdk/**', 'scripts/merge-openapi.mjs', 'docs/audit/**'] });

Entries are repository-relative globs with the same grammar as sources (**, *, ?; no leading /, no .., no trailing /, at most 64). The list does three things:

  • Builds. A push builds the environment when it touches the build path or any entry; before, only the build path could start a build, so a change to something the build reads rebuilt nothing until the next push to the build path. See Monorepos and build_path.
  • Reuse. A step that lists no sources depends on the build path and the watch set instead of on the whole repository, and is reused when none of them changed (reuse auto; never when the step declares egress). A step that lists sources keeps exactly those, and a native step is never scoped. The first build after a pipeline adopts watch runs those steps once, because their declared inputs changed.
  • Tests. For a test step that uses Canopy’s test selection, a changed path outside the build path that no entry matches cannot have started the build and is left out; a matching one selects the tests that read it.

Anything a step reads outside the build path and the watch set is invisible to all three, so list it. Host stores the list on the environment each time a build generates the pipeline (watch_paths, read only: canopy environments show prints it and the environment Settings page names it under the build path). It needs @canopy/ci 0.37 or later; an older generator ignores the field and Host refuses a generator image that predates it.

Every step (an ExecOp in the graph) runs in its own sandboxed container:

  • Digest-pinned images only. oven/bun:1-alpine:latest is rejected at validation time - a floating tag would make two builds of the same commit non-reproducible. Pin to a @sha256:... digest.
  • No network by default. Declare exactly the hosts a step needs via egress: ['registry.npmjs.org', ...] - plain hostnames or a single leading wildcard label (*.example.com). An undeclared host is not reachable, not silently allowed.
  • Declared resources. resources: { memoryMb, cpus, pidsLimit } and timeoutSeconds - a step that doesn’t declare enough for what it actually does fails clearly (OOM/timeout), rather than starving something else silently.
  • No shared filesystem and no cache mounts. A step starts from a clean sandbox. What carries over between runs is a step’s result: name the files it depends on with sources (see “Which files a step reads” below) and an unchanged step is not run again.
  • Secrets, never inlined: secret('NAME') from the secret helper resolves a value stored in Vault at run time - the pipeline file itself never contains one. Manage them with canopy pipeline-secrets (see below).

A step that hasn’t changed - by actual content, not by name - doesn’t re-run; a step whose declared inputs are already known-cached is pruned from the plan before anything executes.

Editor/type support for a canopy.pipeline.ts outside a JS package

Section titled “Editor/type support for a canopy.pipeline.ts outside a JS package”

Working inside host/mcp/, cortex/api/, forest/, or the repo root - none of which have their own node_modules - your editor’s TypeScript server won’t resolve @canopy/ci on its own. This repo’s root tsconfig.pipelines.json maps it (and @canopy/docker) straight to the real sdk/packages/*/src for exactly this case:

Terminal window
bunx tsc -p tsconfig.pipelines.json --noEmit

Point your editor’s TypeScript server at that config for a canopy.pipeline.ts living outside a JS package, and you get real in-editor type checking with no package.json added to a Python/Go package just for this. canopy pipelines check (below) is self-sufficient and doesn’t need this - this is purely for editor/LSP support and a CI-independent tsc --noEmit pass.

Open an environment, go to its pipeline definition and choose Edit pipeline. The editor reads the canopy.pipeline.ts from the repository, at the environment’s branch and build path, and shows it two ways that always agree:

  • Steps is a diagram of the steps with a panel for the one you select. The panel changes the step’s image and command, CPUs, memory, timeout, whether it needs a GPU, how many attempts it gets, whether a failure fails the pipeline, and whether it runs always or only on a branch, a tag, an event or a pull request. Add a step and Remove step work on the diagram too.
  • Code is the file itself, with syntax errors marked on their line.

The editor changes only what it can read. A value written as a plain literal, or as a constant declared at the top of the file, is edited in place. A step or option built any other way (a computed value, a spread, a helper function) shows as Defined in code: you can see it and change it in the code view, and the editor never rewrites it behind your back. Network hosts are shown by name. Under Security you tick the team’s pipeline secrets that a step may read; the secrets themselves are managed on the team’s Pipeline secrets page.

Check pipeline compiles your unsaved text in the same isolated sandbox Canopy uses for real builds and plans it for your team, without running a step. It reports a syntax error with its line, a graph that cannot be planned, or a promotion policy that denies it. Review and save stays unavailable until the text you are about to save has passed a check.

Saving is a commit to the environment’s branch or, when the branch is protected or you would rather have a review, a pull request from a new branch, which Canopy opens in the background and the dialog waits for. If the branch deploys on every push, the dialog says that the commit starts a deploy. If someone changed the file since you opened it, saving is refused and the editor reloads the latest version so you can make your change again. People who may look at an environment but not deploy to it see the pipeline read-only.

Run now starts a build of the environment’s branch, exactly as a push would, and is available once your changes are saved. Every project also has a Pipelines tab that lists its environments’ pipelines with links to view, edit and run each.

A repository with no canopy.pipeline.ts offers a starter that fits the project (a single build step, a Dockerfile build, or tests for Node.js, Python or Go) to begin from; nothing is written until you save it.

A secret is a named value that a step can read, for example secrets: [secret('NPM_TOKEN')]. In the app, open Team → Pipeline secrets to add one, change its value or remove it. A value is stored encrypted, is never shown again, and a secret name is a letter or underscore followed by letters, digits and underscores. The same list is available as canopy pipeline-secrets (below). A secret reaches the pipelines of pull requests only when it is marked for them, and never a pull request from a fork: see Pipelines on pull requests.

Terminal window
canopy pipelines check ./canopy.pipeline.ts

Compiles, determinism-checks, and validates the file entirely offline

  • no network call, no Canopy account required. It reproduces the same double-compile Canopy itself runs server-side (frozen clock, seeded randomness) to catch nondeterministic authoring before it ever reaches a pipeline.generation_diverged incident, runs the same validate() the server runs, and prints the solved shape: topological order, critical path, dead nodes (no path to a deploy/promote/etc.), declared egress hosts, declared secret refs, and declared resources against the platform maximums. Exits non-zero on any failure, so it’s safe to use as a step in another CI system, or inside a pipeline step after installing the Canopy CLI in that step’s image.

--ref, --commit, --commit-time, --event, --repository-id, and --untrusted let you simulate the context a real generation run would have (e.g. --untrusted --event pull_request to check what an untrustedPullRequest() branch compiles to for a fork PR); every one has a stub default so plain canopy pipelines check <file> works with no flags at all.

To check a file against the real server instead, with the plugin and image locks of an environment’s branch and the team’s policies, run canopy config-files validate --env <environment_id> -f canopy.pipeline.ts. It is the same check as Check pipeline in the editor and changes nothing.

What this can’t check: plugin tarball integrity/yank status (needs the registry a real generation run verifies against - any canopy.plugins.lock entry is reported back labelled unverified) and server-side Stage-2 policy (untrusted-strip, promotion policy, plugin permission manifests). For those, push and use canopy pipelines validate/plan against the real generated graph.

canopy.environment(id) is the one place a pipeline reaches outside its own sandboxed steps, and it’s deliberately not a plugin surface - every method here emits a first-class PlatformOp node, gated by the exact same promotion-policy checks (require_evaluation_score, required approvals, etc.) that already govern these actions everywhere else in Canopy:

canopy.environment(id).deploy({ inputs: [test] });
canopy.environment(id).promote({ inputs: [test], fromEnvironmentId: stagingId });
canopy.environment(id).rollback({ inputs: [] });
canopy.environment(id).scale({ inputs: [] });
canopy.environment(id).invalidateCache({ inputs: [], cacheKey: 'edge' });
Terminal window
canopy pipelines generate <environment_id> --at build:142

--at is head (the environment’s branch), branch:<name>, tag:<name>, sha:<full sha> or build:<number or id>. The server turns it into one commit with your own provider account (a tag is followed to the commit it points at, annotated tags included; an unknown tag is 404 revision_not_found, and the commit, never the tag name, is what is stored), then reads canopy.pipeline.ts, canopy.plugins.lock and canopy.images.lock at that commit, so a push that lands while the request runs cannot change what is compiled. The answer names the commit the graph was generated from. --ref <ref> still works, and a --commit you add is only a check: if it is not what the ref resolves to now, the request is refused with 409 revision_mismatch (the body names the commit it resolved to) and nothing is stored. The pipeline sees the commit’s own time as its clock; if the provider cannot return it the request fails with 422 commit_time_unavailable rather than using the current time. Generating stores a graph, so it needs environment:deploy. Builds use the same rule: the graph of a build is compiled from the commit the build pinned.

Already have a CI config? canopy pipelines import converts it into a CPG instead of asking you to hand-author one from nothing:

Terminal window
canopy pipelines import <environment_id> --from github-actions --file .github/workflows/ci.yml --ref main --commit <sha>

Only --from github-actions is implemented today, and it’s deliberately partial: strategy.matrix, services:, if: conditionals, reusable workflows, and third-party marketplace actions have no CPG equivalent - these are reported as warnings in the output, never silently dropped.

Going the other way, canopy pipelines eject <graph_id> exports a stored graph back out as a plain GitHub Actions workflow (one job per node, preserving real parallelism) - the explicit anti-lock-in escape hatch, never the actual execution path Canopy itself uses.

A step’s sources list names the repository files its result depends on (sources: ['src/**', 'package.json']); a step without one depends on the whole repository, or, when the pipeline declares a watch set, on the build path and the watch set. Canopy calls them declared inputs and uses them to decide whether a finished result can be reused. With the host.source feature on, canopy pipelines node-source <build> <node> --env <id> shows them for one step: the commit its checkout pinned, the files the globs match at that commit, the declared inputs that changed since the step’s previous run, and the reason it ran or was reused in plain words (for example “The repository file list at this commit could not be read, so it cannot tell which declared inputs changed and ran the step”). The Source page of the API (GET …/source/repositories/{id}/declared-inputs) answers the other way round: which steps declare a given file. Both say “declared input”, never that a file caused a run. See Canopy Source.

Command Purpose
canopy pipelines graph <build_id|graph_id> Show a compiled graph’s nodes, ops, and dependencies; supports --json
canopy pipelines plan <graph_id|local-file> Plan a stored graph or local graph JSON; local planning requires --team <team_id>. Supports --untrusted --pr-number <n>, --driver-mode, --verbose, and --json. Executes nothing
canopy pipelines stats --env <environment_id> [--days <n>] How many of the environment’s pipeline runs were reused instead of executed over the trailing days (default 7), the estimated time that saved, and the p50 and p95 of how long runs waited and took; supports --json
canopy pipelines resources --env <environment_id> [--days <n>] For each step of the environment’s recent builds that reported measurements: how often it ran, the memory it declared, its p99 and maximum use, and the memory and CPUs it should ask for (the p99 with 25% headroom, never below the most it used, rounded up to 64 MB; steps with fewer than five runs get no recommendation). Advice only; supports --json
canopy pipelines diff <graph_id> <against_graph_id> Structural diff - added/removed/changed nodes plus a policy delta (new egress hosts, new secret refs, new platform ops, removed gates)
canopy pipelines generate <environment_id> --at <revision> Compile that environment’s canopy.pipeline.ts at one commit hermetically and store the result (--ref <ref> [--commit <sha>] still works); supports --untrusted and --json
canopy pipelines node-source <build> <node> --env <environment_id> The source behind one step of a build. Needs host.source; supports `–only files
canopy pipelines import <environment_id> --from github-actions --file <path> --ref <ref> --commit <sha> Convert an existing CI config into a stored graph
canopy pipelines eject <graph_id> [--out <path>] Export a stored graph as a plain GitHub Actions workflow
canopy pipelines plugins tree <environment_id> --ref <ref> Show plugins locked at a ref; --verify exits non-zero if a locked plugin fails verification
canopy pipelines check <canopy.pipeline.ts> Offline: compile + determinism-check + validate a local .ts file, no network call. Prints the solved graph shape
canopy pipelines validate <local-file> Plan a local graph file, pass/fail only (exit code 1 on failure) - for a CI step
canopy config-files validate --env <environment_id> -f <canopy.pipeline.ts> Check an unsaved file against the real server: compile it in the generator sandbox with the environment’s locks and plan it for the team. Nothing is saved or run; exits 1 when it is not valid
canopy config-files show --env <environment_id> --kind pipeline [--content] Where the environment’s canopy.pipeline.ts is in its repository, its sha, and whether your connection may write it
canopy pipelines run <graph_id> Real execution - an ExecOp runs in a real sandboxed container, a PlatformOp can trigger a real deploy/rollback/cache-invalidation. Asynchronous - poll with status
canopy pipelines status <graph_id> Per-node execution state for a graph’s most recent run
canopy pipelines approve-gate <graph_id> <node_id> Approve a blocked gate node and resume its run
canopy pipelines reject-gate <graph_id> <node_id> Reject a gate node - fails it, which fails the run fast like any failed node
canopy pipeline-secrets set <name> <value> --team <team_id> Set (or rotate) a pipeline secret. Stored in Vault only, never in Postgres, never returned by any command
canopy pipeline-secrets list --team <team_id> List a team’s pipeline secret names (never values)
canopy pipeline-secrets rm <name> --team <team_id> Remove a pipeline secret
canopy pipeline-secrets pull-requests <name> --team <team_id> (--allow | --forbid) Allow or forbid a pipeline secret for pull request runs

Is this the same as Canopy Connect? No. Canopy Connect imports and correlates CI you already have - your existing GitHub Actions, GitLab CI, or Bitbucket Pipelines config, unmodified. Canopy Pipelines is for writing new pipeline logic yourself, in TypeScript.

Do I need a canopy.pipeline.ts file? No. Without one, your project builds and deploys exactly as it does today.

What happens if a step fails? The gate fails loudly and the deploy never reaches the legacy build path - not a warning buried in a log, a real stop, leaving your previous release untouched.

Is this available on every plan? The feature manifest lists host.pipeline_graph as public and enabled by default, with no subscription entitlement encoded in that feature entry. The API routes are preview and unstable. Steps that need a specific machine (a native Mac or Linux node, a GPU) also require that machine capability to be available to your team.

An environment created with package_build: true (see Environments) builds, tests and publishes a package and deploys nothing. Its canopy.pipeline.ts is one call:

import { definePackageBuild } from '@canopy/ci';
export default definePackageBuild({ package: '@canopy/ui', dir: 'library' });

definePackageBuild (in @canopy/ci 0.34.3) adds the steps checks, plan-release, version, pack, optional consumer-n steps, publish, dist-tag and verify, all in a digest-pinned Bun image, with no image build. A change file (Changesets format, <dir>/.changeset/<name>.md) names the package and the bump; a push with none ends successful as “Nothing to release”. The publish, dist-tag and verify steps are generated only for a push and use the pipeline secret NPM_TOKEN; any other event (a pull request, a tag, a schedule) runs the checks, plan, version and pack steps and publishes nothing. A version that fails the install check after publishing is deprecated and the dist-tag goes back to the previous version; nothing is ever unpublished.

Every step of a package build environment receives CANOPY_BUILD_ID and, when the build has one, CANOPY_COMMIT. The publish sends them to the registry with the change files, the changelog entry and the files of the release commit (the version bump, the changelog and the consumed change files). The registry checks that the build belongs to the team that owns the scope, links the published artifact to that build and commit, and keeps one release record per published version. After the publish, Canopy opens a release merge request from the account that published (the owner of the registry key): a branch canopy/release-<package>-<version> from the environment’s branch with the version bump, the changelog and the consumed change files removed, then merges it once its checks pass (squash). A request that stays open because the provider cannot merge from Canopy (Bitbucket) is merged there. The merge touches only the package folder, so the package build runs again and ends “Nothing to release”. A release whose request could not be opened or merged is marked failed with the reason; the published version is not affected. The team gets a notification when a package build publishes a version (package.published) and when a release merge request fails (package.release_failed); both appear in Activity. On a GitHub pull request or GitLab merge request into the environment’s branch that changes the package folder, Canopy posts the commit status canopy/change-file: success when the request adds a change file (an empty one from --none counts), failure otherwise. Requests from forks and Bitbucket are not checked. Creating a package build environment, or sending package_build: true to an existing one, subscribes the repository’s webhook to pull request events so the check can run.

canopy packages change <@scope/name> --bump patch|minor|major --summary "<what changed>" writes the change file; canopy packages change --none writes an empty one, which records that a change needs no release. canopy packages releases <@scope/name> lists each version with the build and commit that made it and the state of its release merge request, canopy packages show adds the dist-tags, and the build’s detail (canopy builds show, GET /builds/{id}) has a package_release object with the same record for that build.