Skip to content

Canopy Source

Canopy Source is a view of the repositories an environment builds from: their branches, files, history and the changes between two revisions. It reads from your git provider on demand; Canopy keeps no copy of your code. Pull requests and merge requests, with a merge gate and merge, close, comment and review, are a separate preview feature: see Pull requests in Canopy Source.

The host.source feature is generally available and enabled by default. While staff have it switched off, Host API routes return 403 with error: feature_disabled. GitHub and GitLab repositories are supported. Bitbucket repositories are listed but cannot be read yet.

Reading needs the source:read permission (developer and above). Canopy reads a repository as you: with the provider account you connected, or with a GitHub App installation you own that covers the repository’s owner. It never falls back to a team credential and never to another provider. If you have no usable credential the answer is 403 with error_code: credential_missing and a suggested_action such as “Connect your GitLab account”; a stale one answers credential_expired. A provider refusing a repository answers forbidden (the provider’s 401 never becomes a 401 from Canopy, so your Canopy session stays valid). Disconnecting a provider stops reads on the next request.

An environment with the feature on has a Source entry in its sidebar, right after Overview, with three sections.

  • Browse shows the file tree, a file with syntax colours and line numbers, and a context panel with what is deployed, how far the branch head is ahead of it and which services build from the path you are looking at. Select lines to put #L10-L20 in the address; press y for a permanent link that names the exact commit.
  • History lists commits grouped by day, marks the deployed commit and the branch head, and opens a commit with its parents. A merge commit can be compared against either parent.
  • Changes compares two revisions of one repository. Exact difference shows everything that differs between the two; Changes since branch point shows what the head changed since it left the base’s history. Files are listed in a tree with their status in words and counts, can be marked viewed, and open in a unified or split view.

Every view says which revision it shows (“Deployed”, “Branch head main”, a build, a release or a commit) and never calls a branch head “current”. When a provider returns only part of an answer, a notice names the provider’s limit and how much was returned; partial results are never described as complete. Press ? in Source for the keyboard shortcuts.

Repositories you cannot read are listed with what to do about it, for example “Connect your GitLab account”. Build pages link to Source for each repository the build used.

GET /environments/{environment_id}/source/repositories

Lists every active repository row of the environment with its provider, branch, the services that build from it, the commit currently deployed and what you can do with it:

{ "repositories": [ {
"id": "7c0f…", "provider": "gitlab", "path": "acme/shop", "provider_repository_id": "48213",
"is_primary": true, "branch": "main", "web_url": "https://gitlab.com/acme/shop",
"services": [ { "id": "…", "name": "web", "source_path": "apps/web" } ],
"deployed": { "release_id": "…", "pins": [ { "sha": "a1b2…", "services": ["web"], "origin": "built", "provenance": "recorded" } ] },
"access": { "state": "ok", "via": "user" }
} ],
"image_services": [ { "name": "cache", "image": "valkey/valkey:8" } ] }

id is the Canopy repository row id; use it in every route below. A row you cannot read is listed with access: { "state": "denied", "reason": "credential_missing", "fix": "Connect your GitLab account" }; a row on a provider Source does not read yet has access.state: "unavailable". provenance is recorded when the build stored its pins and inferred when Canopy had to take the build’s commit instead. origin is built, carried, image or origin_unknown for a release recorded before origins existed (never null). The list is cached for 30 seconds per user.

GET …/repositories/{repository_id} reads one repository from the provider, which also proves you can see it, and returns capabilities: what differs between providers, for example whether a direct comparison is reconstructed (direct_compare: "reconstructed" on GitHub) or whether file history follows renames (file_history: "native" on GitLab).

The rows above are environment attachments: a provider repository attached to three environments is three rows. A source repository is the team-level identity underneath them, one per (team, provider, provider repository id), however many environments attach it and including a repository that no environment builds. Two teams that connect the same provider repository have two source repositories; neither can see the other’s.

GET /source/repositories?team_id={team_id}[&project_id={project_id}][&cursor=…][&limit=50]
GET /source/repositories/{source_repository_id}

Both need source:read on the owning team and the host.source feature. A page is ordered by path (case-insensitive), then id; next_cursor is null on the last page, limit is 1 to 100. project_id keeps the repositories one of that project’s active attachments uses. A caller who is not a member of the owning team gets the same empty 404 as for an id that does not exist.

{ "repository": {
"id": "5b1e…", "team_id": "…", "provider": "github", "provider_repository_id": "123456789", "path": "acme/shop",
"default_branch": null, "webhook_registered_at": "2026-11-19T10:00:00Z", "webhook_verified_at": "2026-11-19T10:00:04Z",
"automation_identity_id": null, "pr_sync": "off", "dependency_updates_enabled": false, "attachment_count": 3,
"created_at": "…", "updated_at": "…" } }

A source repository exists once an attachment has its provider repository id (the identity backfill stamps it and links the attachment on its next run, at most 30 minutes). Canopy keeps one webhook per source repository, at /repositories/hooks/{source_repository_id}, signed with a secret of its own that no route returns; one delivery is claimed once and fanned out to the environments that attach the repository. The older per-environment webhook URLs keep working until they are retired. webhook_verified_at is set by the first signed delivery Canopy accepts. To let Canopy automation write to a repository, bind an automation identity to it (see Clone identities).

Everything that reads content takes a commit SHA, so a view can be reproduced later. Turn a name into a SHA once:

GET …/repositories/{repository_id}/revisions/resolve?at=branch:main

at is one of sha:<hex>, branch:<name>, tag:<name>, head (the branch the repository row is configured for), deployed (the commit of the active release), build:<number or id> or release:<id>. The answer carries the sha, the ref it came from, whether it came from the provider or from a recorded pin, and how it relates to what is deployed (relation_to_deployed: same, different or unknown). If a build pinned more than one commit of the repository the answer is 409 revision_ambiguous rather than a guess. preview:<id> is not available yet.

GET …/tree?sha=<sha>&path=src/lib&limit=100&cursor=… one directory level, directories first
GET …/paths?sha=<sha> every file path (capped at 20,000), for quick open
GET …/blob?sha=<sha>&path=src/app.ts[&max_bytes=…][&lines=…] one file
GET …/branches?query=feat&limit=50&cursor=…
GET …/commits?sha=<sha>[&path=src/app.ts]&limit=30&cursor=…
GET …/commits/{sha} one commit with its parents
GET …/commits/{sha}/changes?parent=1&cursor=… the files a commit changed against a parent

Symlinks and submodules appear as typed entries and are never followed. A file is returned as UTF-8 text up to 1 MiB; binary files, Git LFS pointers (Canopy does not download LFS content), symlinks (with their target) and submodules are described instead, and a larger file has truncated: true and no content.

Add lines=<n> (1 to 5000) to read the start of a text file that is over the limit: content is then its first n lines, at most 512 KB of text, cut at a line boundary and never inside a UTF-8 character, and completeness is { "state": "truncated", "reason": "first_lines", "loaded": <lines returned>, "total": null }. Canopy fetches only that prefix from the provider (a range request, or the stream is closed after the cap), so a 100 MB file costs about as much as a 1 MB one. Binary files, Git LFS pointers, submodules and symlinks never return content, with or without lines. Every blob carries completeness: complete for a whole file, and truncated with reason blob_too_large for an oversized file read without lines.

commits?path= lists only commits touching the path. On GitLab it follows renames; GitHub and Bitbucket do not. commits/{sha}/changes compares against parent 1 by default; a merge commit has a parent=2.

An environment whose services build from a subdirectory of a monorepo (for example host/api) sees only that directory. The repository list reports it as scope_path.

The scope is stored on the environment as source_scope and set with canopy environments update --source-scope, the Source folder field on the environment’s Settings page, the MCP update tool or PUT /environments/{id} ("" means the whole repository, null means follow the services). It applies to the primary repository and starts out as the directory the services build from; changing the primary service’s build path moves it along while it still equals the old path. A repository without a stored scope uses the deepest directory its services share, and a service built from the repository root leaves the whole repository in scope.

  • tree without a path opens at scope_path, and commits without a path lists the history of scope_path.
  • tree, blob, commits and compare/file answer 400 for a path outside scope_path.
  • paths, commits/{sha}/changes and compare leave out files outside it, and compare reports its totals as null because the counts would cover files the environment cannot read.
GET …/compare?base=<sha or token>&head=<sha or token>[&mode=direct|merge_base][&cursor=…][&commits_cursor=…]
GET …/compare/file?base=…&head=…&path=src/app.ts[&previous_path=…][&mode=…]

Additions are always lines present in head and absent in base, on every provider. mode=direct (the default) is the exact difference between the two trees; mode=merge_base is what head changed since it left base’s history. Unrelated histories compare directly; in merge_base mode they answer 422 no_common_ancestor. The answer has relation (identical, ahead, behind, diverged, unrelated), ahead_by, behind_by, the commits and the changed files with totals.

Each file has a patch.state: included (the hunks are in patch.text), lazy (fetch it with compare/file), too_large, binary, empty (a pure rename or a mode change) or unavailable. GitLab, for example, returns the first 100 files of a large comparison with their hunks and the rest as lazy.

strategy says how Canopy obtained the answer: provider_compare, reversed_compare (GitHub answered the reverse question and Canopy inverted it) or tree_diff (Canopy diffed both trees itself, which GitHub needs for diverged branches, unrelated histories and comparisons over its 300-file cap). A tree_diff detects only exact renames (rename_detection: "exact_only") and has no line counts until a file’s patch is fetched.

GET /environments/{environment_id}/source/snapshots/{snapshot}[?limit=50&cursor=…]

A snapshot is the source of a whole environment at one moment, one pin per repository. snapshot is deployed (the active release), build:<number or id>, release:<id>, preview:<id> or heads (the head of each repository’s configured branch). Everything except heads is read from Canopy’s own records and makes no provider call, so it answers even when you have no provider account connected.

{ "snapshot": { "token": "deployed", "kind": "deployed", "state": "present", "build_id": "…", "build_number": 142,
"release": { "id": "…", "kind": "build", "status": "active", … }, "preview": null },
"pins": [ { "repository": { "id": "7c0f…", "provider": "github", "path": "acme/shop", "active": true, … },
"sha": "a1b2…", "ref": "main", "provenance": "recorded", "origin": "built",
"services": [ { "id": "…", "name": "web", "source_path": "apps/web", "origin": "built" } ] } ],
"image_services": [ { "id": "…", "name": "cache", "source_path": "", "origin": "image" } ],
"next_cursor": null, "completeness": { "state": "complete" } }

Two repositories can be on different providers in one environment; each pin names its own. Two services of one repository that were pinned at different commits are two pins. Services that run an image and have no Git source are listed apart in image_services.

Canopy does not guess what it did not record. provenance says how a pin is known: recorded (stored when the build ran), inferred (reconstructed from the build of a release that predates pins: the commit is the one that build ran, but which services it covers is not recorded), missing (nothing was recorded; the snapshot is then partial with reason pins_missing) and, for heads, resolved. A service build from before Canopy stored whether the service was built or carried has origin: "origin_unknown", never built. A rollback release shows what it restored with origin: "carried" and names the release it restored in release.source_release_id. A repository detached since stays in old snapshots with active: false.

heads reads each branch head with your own provider access, so a repository you cannot read has unavailable: { "reason": "credential_missing", "fix": "Connect your GitLab account" } instead of a commit, and the snapshot is partial with reason heads_unavailable. deployed of an environment that was never deployed answers state: "not_deployed" with no pins. Snapshots are paged by repository, 50 at most per page.

GET /environments/{environment_id}/source/changes[?from=deployed&to=heads][&mode=direct|merge_base][&limit=50&cursor=…]

Compares two snapshots (from defaults to deployed, to to heads; any snapshot token works, for example from=release:<id>&to=release:<id> or from=deployed&to=preview:<id>). The comparison is per repository: Canopy never diffs commits of different repositories, and never draws one combined diff.

status meaning
changed / unchanged the repository is in both snapshots; identical pins are unchanged without asking the provider
added / removed the repository is in only one snapshot
replaced the same path in from and to is now a different provider repository (replaced.from, replaced.to)
unavailable you cannot read it (reason such as credential_missing or forbidden, with a fix), the provider is not supported yet (provider_not_enabled), a pin was not recorded (pin_missing) or the provider failed. The pins are still shown

Two rows that are the same provider repository (a repository detached and attached again, or renamed) are compared as one. A repository whose services were pinned at several commits yields one entry per pair of commits, up to six.

Each entry has base and head (sha, ref, provenance), relation, ahead_by, behind_by, files, additions, deletions, its own completeness, and its services. A service is affected when a changed file is under its source_path (a service that builds from the whole repository is affected by any change); a carried service is never affected (reason: "carried"); null says it cannot be told (comparison_unavailable, files_incomplete). Canopy reads at most three pages of the changed-file list to decide this.

Besides the repositories, services lists services whose origin differs between the snapshots (for example built to carried), and deployment_changes lists what does not come from Git: an image digest that changed on an image-only service, a service configuration that differs (config, with hashes), services added or removed. Each side is read from the services its release recorded; a rollback release without its own records uses the ones of the release it carried, and a release with neither uses the images its service builds recorded, in which case configuration changes cannot be listed and deployment is { "state": "partial", "reason": "config_not_recorded", "fix": "…" }. When a side has nothing at all, deployment is { "state": "unavailable", "reason": "release_has_no_service_records", "fix": "…", "missing": ["from"] }; deploying the environment again records its services. completeness is partial with reason repositories_unavailable when any repository could not be compared.

GET …/repositories/{repository_id}/commits/relations?shas=<sha>,<sha>,…

For a history list: how many builds, releases, previews and pipeline runs used each of up to 50 commits, as { "items": { "<sha>": { "builds": 2, "releases": 1, "previews": 0, "pipeline_runs": 3, "truncated": false } } }. Counts only, from a fixed number of queries however many commits you ask about, with no provider call. A commit nothing used has zeros, and a count stops at 50 with truncated: true. The per-commit route below lists the rows.

GET …/repositories/{repository_id}/commits/{sha}/relations

The builds, releases, previews and pipeline runs of this environment that used a commit of the repository. A commit counts for a repository, not for a SHA alone: every row of the environment that is the same provider repository counts, detached rows included, and the same SHA in another repository does not. A build is recorded when it pinned the commit for the repository and inferred when it predates pins and ran this commit for this repository according to its build row. Previews match by pull request head (via: "head") or by a preview build that pinned the commit (via: "service_build"). Each list is cut at 50 items and says so (truncated). It is read from Canopy’s records and needs no provider account. The Engineering Graph does the same across environments of your teams: GET /graph/commits/{sha}?repository=<row id | provider:provider repository id> also finds builds that pinned the commit in a service build, and without repository a SHA shared by two repositories matches both.

A step of a canopy.pipeline.ts lists the files it reads in sources globs (src/**, package.json); a step that lists none depends on the whole repository. Canopy calls the files a step lists its declared inputs. It never says a file caused a run, a reuse or a failure: a declared input is what the step said it reads, nothing more.

GET …/repositories/{repository_id}/declared-inputs?sha=<full sha>&path=src/app.ts

path is a file, or a directory with type=directory; without it every step that reads the repository is listed. The answer is read from Canopy’s records (the pipeline graphs of the 20 newest builds that pinned the repository), so it needs no provider account:

{ "outcome": "matched",
"basis": { "runs_examined": 12, "runs_limit": 20, "more_runs_exist": false, "graphs_examined": 3, "runs_at_revision": 2, … },
"inputs": { "items": [ {
"node_id": "test-web", "declaration": "globs", "globs": ["src/**", "package.json"],
"match": "glob", "matched_glob": "src/**", "label": "Declared input (src/**)",
"latest_run": { "build_number": 142, "status": "succeeded", "pinned_sha": "a1b2…", "at_revision": true,
"reuse_decision": "reused", "reuse_reason_code": "INPUTS_UNCHANGED", "reuse_explanation": "…" } } ],
"next_cursor": null },
"explanations": { "INPUTS_UNCHANGED": "…" }, "completeness": { "state": "complete" } }

outcome is no_matching_nodes when runs were read and none declares the path, and no_pipeline_runs when no build that pinned the repository has a pipeline run, which means nothing is known, not that no step reads the file (completeness is unavailable with that reason). match is glob for a file, prefix for a directory a glob can match something below, whole_repository for a step that declares nothing. A step’s globs come from the newest run that contains it. When more than 20 runs exist, a stored graph could not be read, or the page is cut, completeness is partial.

GET /environments/{environment_id}/builds/{build_id}/nodes/{node_id}/source

build_id is the build id or number. The answer has these parts, each stating what it could and could not read:

  • source: the checkout the step depends on (repository, ref and the commit the pipeline graph pinned), and whether the build’s recorded pins agree, differ or were not_recorded. A step with no checkout has state: "no_source".
  • declared_inputs: the step’s globs, or the whole repository, with a ready label such as “Declared input (src/**)”.
  • matched_files: the files those globs match in the repository at that commit, sorted, each with the glob that matched, paged with matched_limit and matched_cursor. Read from the provider with your own account.
  • changed_inputs: the declared inputs that differ between the commit of the step’s previous finished run in this environment (looked for among the 25 builds before this one) and this one, from an exact (direct) comparison filtered by the globs; a rename counts when either side matches. compare carries the arguments of the complete comparison for the failed step’s full diff. States: compared, same_revision, no_previous_run, not_comparable (the previous run used another repository), unavailable.
  • reuse: the step’s reuse decision (executed or reused), its reason code and a sentence that explains it, and whether Canopy could compute the step’s execution key. explanations holds the sentence of every code in the answer, for example TREE_MANIFEST_UNAVAILABLE (the repository file list could not be read, so reuse could not be judged) or GRAPH_DEDUP (the result was carried over from an earlier build of the same pipeline and commit).

include=matched_files or include=changed_inputs reads one provider-backed section only. When a provider read is not possible (no connected account, a rate limit, a provider Source cannot read yet), only that section is unavailable, with the reason and a fix; the other parts are still answered. The comparison reads at most 10 pages from the provider and says partial with canopy_page_cap when it stopped; it never reports “nothing changed” from an incomplete comparison.

GET …/repositories/{repository_id} also returns identity: whether the provider repository id Canopy stored for the row still answers at the stored path (verified; identified when it was not stored yet). When the path is gone but the id resolves to a new path, the answer is identity: { "state": "renamed", "current_path": "acme/new", "renamed_from": "acme/old" }, and the other Source routes answer 404 repository_not_found for that row until the path is updated:

POST /environments/{environment_id}/repositories/{repository_id}/path { "path": "acme/new" }

This needs project:blueprint as well as source:read. Canopy checks the rename again with your own provider account, accepts only the path the provider reports (otherwise 409 path_changed; 409 not_renamed when the provider reports no rename), (for a secondary repository) requires your team’s clone identity to be able to read the new path, and records the change in the audit log. The row id, the pins of old builds and the webhook stay. replaced means the old path now belongs to a different repository; that needs a new attachment, not a rename.

Four read-only tools in the source profile of the Host MCP server (CANOPY_HOST_MCP_TOOL_PROFILE=core,source; see MCP Servers) let an agent read what you can read, within a small budget:

tool what it returns
host_source_repositories(environment_id) each repository (id, provider, path, branch, services), the commits deployed and your access
host_source_read(environment_id, repository_id, path, at?) a directory listing (up to 200 entries) or a text file up to 32 KB at at (default head)
host_source_log(environment_id, repository_id, at?, path?, cursor?) 30 commits newest first; continue with next_cursor and the returned sha as at
host_source_compare(environment_id, base, head?, repository_id?, path?, node?) a summary of what changed; the patch of a single file with path; with node (a pipeline step id) and base the build, that step’s source, declared inputs, reuse reason and changed declared inputs

Nothing is cut silently. A file over 32 KB, a binary file, a Git LFS pointer or a submodule comes back with no content and a note; a listing, file list or commit list over its cap sets truncated. host_source_compare without repository_id takes snapshots (deployed, head, build:<n>, release:<id>, preview:<id>) and returns one row per repository like canopy source changes; with repository_id it takes revisions and lists at most 100 files and 20 commits without patches. With node, base is a build number or id and head is not needed: the answer lists at most 20 declared globs, 20 matched files and 100 changed declared inputs, each section with its own state and completeness. For anything larger use the CLI or the API.

Every list says how much of the answer is present, in completeness:

state meaning
complete everything the provider holds for this request
partial Canopy stopped early (a page cap, a provider timeout); more may exist
truncated the provider cannot return more (GitHub’s 3,000-file commit cap, GitLab’s 1,000-file diff limit)
unavailable nothing could be read

Anything but complete has a reason (provider_file_limit, provider_timeout, tree_too_large, canopy_page_cap, and so on). A list that is empty is complete; it never stands in for data that could not be read.

A page with more data has a next_cursor. Cursors are opaque and signed: a cursor only works for the repository, operation and revisions it was issued for, and a changed, truncated or replayed one is refused with 400 invalid_request. compare has two independent cursors, cursor for the files and commits_cursor for the commits.

Answers addressed by SHA (tree, blob, commits, compare with two SHAs) are returned with Cache-Control: private, max-age=31536000, immutable when they are complete. Answers that depend on a moving name or that are incomplete because of a timeout are no-cache. Each user may make 120 requests a minute per environment; a provider rate limit answers 429 with Retry-After. Errors are problem+json with a stable error_code: credential_missing, credential_expired, forbidden, repository_not_found, revision_not_found, file_not_found, invalid_request, rate_limited, response_too_large, unsupported, no_common_ancestor, provider_unavailable.

const source = sdk.environments.source;
const { repositories } = await source.repositories(environmentId);
const repo = repositories[0].id;
const { sha } = await source.resolve(environmentId, repo, "deployed");
const root = await source.tree(environmentId, repo, { sha });
const file = await source.blob(environmentId, repo, { sha, path: "README.md" });
const start = await source.blob(environmentId, repo, { sha, path: "data/big.log", lines: 2000 }); // first lines of a file over 1 MiB
const commits = await source.commitPager(environmentId, repo, { sha, limit: 50 });
for await (const commit of commits) console.log(commit.summary);
console.log(commits.completeness); // the worst state seen while paging
const deployed = await source.snapshot(environmentId, "deployed");
for (const pin of deployed.pins) console.log(pin.repository?.path, pin.sha, pin.provenance, pin.origin);
const changes = await source.changes(environmentId); // deployed -> branch heads, per repository
for (const entry of changes.repositories) {
console.log(entry.path, entry.status, entry.relation, entry.services.filter((s) => s.affected).map((s) => s.name));
}
const counts = await source.commitRelationCounts(environmentId, repo, [sha]); // history list badges
const relations = await source.relations(environmentId, repo, sha);
console.log(relations.builds.items.map((b) => b.number), relations.truncated);
const declared = await source.declaredInputs(environmentId, repo, { sha, path: "src/app.ts" });
for (const input of declared.inputs.items) console.log(input.node_id, input.label, input.latest_run.reuse_reason_code);
const step = await sdk.builds.nodeSource(environmentId, "142", "test-web"); // build number or id
console.log(step.source.commit, step.declared_inputs.label, step.reuse.explanation);
console.log(step.changed_inputs.state, step.changed_inputs.files?.items.map((f) => f.path));
const files = await source.compareFilesPager(environmentId, repo, { base: "deployed", head: "head" });
for await (const changed of files) {
const patch = changed.patch.state === "lazy"
? await source.compareFile(environmentId, repo, { base: "deployed", head: "head", path: changed.path })
: changed;
console.log(changed.status, changed.path, patch.patch.text?.length ?? 0);
}

The …Pager methods return a SourcePager: the first page is loaded when you get it, for await yields every item, pages() yields whole pages, toArray(limit) collects, and completeness is the worst state seen so far. snapshotPager() and changesPager() page snapshots and change sets the same way, and declaredInputsPager() pages the steps of declaredInputs(). builds.nodeSource() lives on sdk.builds because the route is under a build; its lists page with matchedCursor and changedCursor taken from the previous answer.

canopy source repos --env <environment_id>
canopy source ls [<path>] --env <environment_id> [--repo <id|owner/name>] [--at <revision>] [--limit <n>]
canopy source cat <path> --env <environment_id> [--repo <id|owner/name>] [--at <revision>] [--lines <n>]
canopy source log --env <environment_id> [--repo <id|owner/name>] [--at <revision>] [--path <path>] [--limit <n>]
canopy source show [<revision>] --env <environment_id> [--repo <id|owner/name>] [--parent <n>]
canopy source diff <base> <head> --env <environment_id> [--repo <id|owner/name>] [--mode direct|merge-base] [--name-only | --stat | --patch <path>]
canopy source changes --env <environment_id> [--from <snapshot>] [--to <snapshot>] [--mode direct|merge-base]
canopy source pins --env <environment_id> [--build <number or id> | --release <id>]
canopy source relations <sha> --env <environment_id> [--repo <id|owner/name>]
canopy pipelines node-source <build> <node> --env <environment_id> [--only files|changes] [--limit <n>]

--repo takes a repository row id or the provider path (acme/shop) and can be left out when the environment has a single repository; with several, the error lists them. A revision is a full commit SHA, sha:<hex>, branch:<name>, tag:<name>, head, deployed, build:<number or id> or release:<id>, and --at defaults to head. Abbreviated SHAs and bare branch names are refused with the list of accepted forms, so a command never guesses.

  • ls lists one directory (the root without a path), cat prints a text file exactly as stored. cat refuses binary files, Git LFS pointers, submodules and files over 1 MiB with exit code 1; cat --json describes them instead. cat --lines <n> prints the first n lines (1 to 5000) of a text file over 1 MiB and says on stderr how many it showed.

  • log lists commits newest first (30 by default); --path keeps the commits that touched a file or directory.

  • show prints one commit, its message and a status and line count per changed file. For a merge commit --parent 2 compares with the second parent.

  • diff prints a git-style patch of what turns <base> into <head>. --stat prints a status and counts per file, --name-only only the paths, and --patch <path> the patch of one file, which is how to read a file whose patch the comparison listed as not included (--previous-path names the file at <base> after a rename). The revisions are resolved by the server, so deployed and head mean the commit of the repository you diff.

  • changes compares every repository of the environment between two snapshots in one request to GET …/changes: --from (default deployed) to --to (default head, the branch heads). A snapshot is deployed, head (or heads), build:<number or id>, release:<id> or preview:<id>; revisions such as branch:main or a SHA are refused, because a snapshot has one commit per repository (use diff to compare revisions of one repository). One row per repository: changed, unchanged, added, removed, replaced or unavailable with the reason; a repository you cannot read or that was never pinned is a row, not a failure. Below the table, Deployment changes lists what does not come from Git: an image that changed, a service’s configuration, services added or removed. --mode merge-base shows what --to changed since it left --from.

  • pins shows the commit of every repository in one deployment, where each pin came from (built, carried, image or origin_unknown) and whether it was recorded or inferred. It reads the deployed release; --build or --release read another one. Image-only services are listed separately.

  • relations lists the builds, releases, previews and pipeline runs of the environment that used a full commit SHA of one repository. It reads Canopy’s own records, so it works for a repository you cannot read from the provider, and --repo also accepts the id of a detached repository row. A list cut at 50 items says (truncated).

  • pipelines node-source prints, for one step of a build (<build> is a number or id), the checkout it depends on, the declared inputs (“Declared input (src/**)”), the step’s reuse reason with its explanation, the declared inputs that changed since the step’s previous run and the files its globs match. --only files or --only changes reads one provider-backed section, --limit <n> (1 to 200) caps both lists and each list ends with the flag that continues it (--matched-cursor, --changed-cursor). A section that could not be read says why and what to do; the rest is still printed. --json prints the API answer unchanged.

--limit <n> (1 to 5000) caps how many entries, commits or files are printed; pages are followed until it is reached.

Standard output carries only the result. When the answer is not complete, or --limit stopped before the end, the CLI also writes a line to standard error and still exits 0, so scripts can pipe the result and decide what to do:

canopy: result is truncated: GitHub lists at most 300 files of a comparison (300 of 450 loaded)
canopy: more results exist; raise --limit to see them

Exit code 1 means the command failed: no --env, a repository you cannot read, a revision that does not exist, or the feature being off.

--json prints the same fields the API returns, plus the repository and revision the command resolved. repos prints the API answer unchanged. The others print:

command fields
ls repository (id, provider, path), revision (at, sha), path, entries, completeness, has_more
cat repository, revision, blob
log repository, revision, path (or null), commits, completeness, has_more
show repository, revision, parent, commit, files, completeness, has_more
diff repository, base and head (requested, sha), mode (direct or merge_base), relation, merge_base, ahead_by, behind_by, strategy, rename_detection, totals, files, completeness, has_more
diff --patch repository, base, head, mode, file
changes environment_id, from, to (the tokens you gave), from_snapshot, to_snapshot, mode, repositories (per row: repository, status, reason, fix, completeness, relation, merge_base, base, head, ahead_by, behind_by, strategy, rename_detection, totals, services (names), service_effects), repository_count, services, deployment_changes, deployment, completeness
pins environment_id, snapshot, pins, image_services, completeness
relations the API answer: repository_id, sha, repository_ids, builds, releases, previews, pipeline_runs, truncated
pipelines node-source the API answer unchanged (build, node, source, declared_inputs, matched_files, changed_inputs, reuse, explanations, access, completeness)

changes --json changed with the move to the server route: every key it printed before is still there, status can now also be added, removed or replaced (with totals null), and image_services is gone in favour of deployment_changes.

has_more is true when --limit stopped the listing while more existed. The --stat, --name-only and --patch choices change only the text output; diff --json always carries every file it loaded.

A repository that releases packages declares its release trains in canopy.releases.ts. Validate it from a checkout:

canopy release validate

A change that affects a released unit carries a small intent file that says how much the unit moves and why. Write one with:

canopy release change @acme/core --bump minor --summary "Add retries to the client"
canopy release change @acme/internal-docs --none

The command writes <intents dir>/<slug>-<hash>.md and prints its path. Commit it with the change. A major bump needs a paragraph that starts with BREAKING:.

Both commands run the release tool. By default they use canopy-release from @canopy/ci. Set CANOPY_RELEASE_TOOLS_IMAGE to a digest-pinned image reference to run the same tool in a container with no network access and only your checkout mounted.