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.
Who can read what
Section titled “Who can read what”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.
In the app
Section titled “In the app”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-L20in the address; pressyfor 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.
Repositories
Section titled “Repositories”GET /environments/{environment_id}/source/repositoriesLists 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).
Source repositories
Section titled “Source repositories”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).
Revisions and permalinks
Section titled “Revisions and permalinks”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:mainat 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.
Browsing
Section titled “Browsing”GET …/tree?sha=<sha>&path=src/lib&limit=100&cursor=… one directory level, directories firstGET …/paths?sha=<sha> every file path (capped at 20,000), for quick openGET …/blob?sha=<sha>&path=src/app.ts[&max_bytes=…][&lines=…] one fileGET …/branches?query=feat&limit=50&cursor=…GET …/commits?sha=<sha>[&path=src/app.ts]&limit=30&cursor=…GET …/commits/{sha} one commit with its parentsGET …/commits/{sha}/changes?parent=1&cursor=… the files a commit changed against a parentSymlinks 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.
Environments built from a subdirectory
Section titled “Environments built from a subdirectory”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.
treewithout apathopens atscope_path, andcommitswithout apathlists the history ofscope_path.tree,blob,commitsandcompare/fileanswer400for a path outsidescope_path.paths,commits/{sha}/changesandcompareleave out files outside it, andcomparereports itstotalsasnullbecause the counts would cover files the environment cannot read.
Comparing
Section titled “Comparing”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.
What an environment ran
Section titled “What an environment ran”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.
Changes across repositories
Section titled “Changes across repositories”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.
Where a commit was used
Section titled “Where a commit was used”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}/relationsThe 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.
Pipeline steps and the files they declare
Section titled “Pipeline steps and the files they declare”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.
Which steps declare a file
Section titled “Which steps declare a file”GET …/repositories/{repository_id}/declared-inputs?sha=<full sha>&path=src/app.tspath 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.
The source behind one step
Section titled “The source behind one step”GET /environments/{environment_id}/builds/{build_id}/nodes/{node_id}/sourcebuild_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 pinsagree,differor werenot_recorded. A step with no checkout hasstate: "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 withmatched_limitandmatched_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.comparecarries 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 (executedorreused), its reason code and a sentence that explains it, and whether Canopy could compute the step’s execution key.explanationsholds the sentence of every code in the answer, for exampleTREE_MANIFEST_UNAVAILABLE(the repository file list could not be read, so reuse could not be judged) orGRAPH_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.
A repository that was renamed
Section titled “A repository that was renamed”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.
From an MCP client
Section titled “From an MCP client”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.
Completeness
Section titled “Completeness”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.
Pages and cursors
Section titled “Pages and cursors”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.
Caching and limits
Section titled “Caching and limits”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.
From the SDK
Section titled “From the SDK”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 repositoryfor (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 badgesconst 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 idconsole.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.
From the CLI
Section titled “From the CLI”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.
-
lslists one directory (the root without a path),catprints a text file exactly as stored.catrefuses binary files, Git LFS pointers, submodules and files over 1 MiB with exit code 1;cat --jsondescribes them instead.cat --lines <n>prints the firstnlines (1 to 5000) of a text file over 1 MiB and says on stderr how many it showed. -
loglists commits newest first (30 by default);--pathkeeps the commits that touched a file or directory. -
showprints one commit, its message and a status and line count per changed file. For a merge commit--parent 2compares with the second parent. -
diffprints a git-style patch of what turns<base>into<head>.--statprints a status and counts per file,--name-onlyonly 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-pathnames the file at<base>after a rename). The revisions are resolved by the server, sodeployedandheadmean the commit of the repository you diff. -
changescompares every repository of the environment between two snapshots in one request toGET …/changes:--from(defaultdeployed) to--to(defaulthead, the branch heads). A snapshot isdeployed,head(orheads),build:<number or id>,release:<id>orpreview:<id>; revisions such asbranch:mainor a SHA are refused, because a snapshot has one commit per repository (usediffto compare revisions of one repository). One row per repository:changed,unchanged,added,removed,replacedorunavailablewith the reason; a repository you cannot read or that was never pinned is a row, not a failure. Below the table,Deployment changeslists what does not come from Git: an image that changed, a service’s configuration, services added or removed.--mode merge-baseshows what--tochanged since it left--from. -
pinsshows the commit of every repository in one deployment, where each pin came from (built,carried,imageororigin_unknown) and whether it wasrecordedorinferred. It reads the deployed release;--buildor--releaseread another one. Image-only services are listed separately. -
relationslists 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--repoalso accepts the id of a detached repository row. A list cut at 50 items says(truncated). -
pipelines node-sourceprints, 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 filesor--only changesreads 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.--jsonprints 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.
Completeness on the command line
Section titled “Completeness on the command line”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 themExit 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.
Release configuration and change intents
Section titled “Release configuration and change intents”A repository that releases packages declares its release trains in canopy.releases.ts. Validate it from a checkout:
canopy release validateA 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 --noneThe 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.