Repository sources and commit statuses
A multi-repository environment builds its services from more than one repository. For attaching repositories, choosing a service’s repository, feature availability and preview behavior, see Multi-repository environments. This page covers source attribution and build commit statuses. The environment still has one primary repository (the one it was created from, and the source of its default service); a team admin can attach secondary repositories, and each service names the repository it builds from. A push to one repository rebuilds only that repository’s services; the other services keep the images of the live release, and the result is one release.
It sits behind the host.multi_repository platform feature, which is generally available and enabled by default;
while staff have it switched off, environment repository routes answer 403 with error: feature_disabled. The CLI also
checks feature availability before listing environment repositories or running attach, update and detach commands.
Cloning a secondary repository needs a team clone identity that covers it.
Where each service came from
Section titled “Where each service came from”Every response that describes services or releases names the repository, whether the environment has one repository or several.
Services. Each object of GET /environments/{environment_id}/app-services (and of create, update and apply) has a
source:
{ "name": "worker", "source": { "repository_id": "6c0f…", "repository": "acme-robotics/fleet-worker", "provider": "gitlab", "branch": "production" }}source is null for an image service and for a service whose repository is no longer attached. The default service
and every service of the primary repository show the primary repository and the environment’s branch.
Releases and builds. GET /environments/{environment_id}/releases (and /releases/{release_id}), and the build
detail GET /environments/{environment_id}/builds/{build_id}, have sources, one entry per service:
{ "sources": [ { "service": "web", "repository_id": "…", "repository": "acme-robotics/fleet-shop", "commit": "a1b2c3d…", "ref": "main", "origin": "carried" }, { "service": "worker", "repository_id": "…", "repository": "acme-robotics/fleet-worker", "commit": "9f8e7d6…", "ref": "production", "origin": "built" }, { "service": "cache", "repository_id": null, "repository": null, "commit": null, "ref": null, "origin": "image" } ]}origin is built (built from commit in this release), carried (the image of an earlier release, unchanged; the
commit is the one it was built from) or image (an image service). A release from before sources were recorded reads
every repository service as built with no repository.
GET /environments/{environment_id} has repository_count, the number of active repositories (1 for an ordinary
environment). It is on a single environment only, not in lists.
Commit statuses
Section titled “Commit statuses”For an environment with two or more repositories, Canopy posts one status per repository and commit of every build,
with the context canopy/build:
| State | When |
|---|---|
pending |
the build is queued or running |
success |
every service built from that repository succeeded (a build waiting for deploy approval counts) |
failure |
a service built from that repository failed, or the build failed before it was built |
error |
the build was cancelled, rejected or errored on Canopy’s side, or a newer build superseded this commit |
The description lists the services built from that repository (Built api, web, Failed building worker,
Superseded by build #12 (worker)), and the target URL opens the build page, where each service’s pin and each status
are shown. On GitLab the states are sent as pending, success, failed and canceled.
- A repository whose services were all carried (not rebuilt) gets no status for that build.
- A commit gets a status once the build has resolved it: a repository pinned to its branch head is reported as soon as the worker has read the head.
- The same state is posted once. A build never goes back to
pendingafter a final state. - When a newer push supersedes a build, the commit that the newer build does not build is closed as
error. A commit both builds share keeps itspending. - Posting uses the team clone identity with the
statuspurpose: a GitHub App installation token limited to the one repository withstatuses: write, or a GitLab token the admin declared withstatus_write. A fork pull request never uses it, and neither does a preview build. - A status that cannot be posted (no identity, an expired token, the provider refusing) never fails or delays the
build. It is recorded: the build detail’s
commit_statusesshows it withdelivery: "failed"and the reason, and the next change of state tries again. - An environment with one repository gets no status from Canopy, as before.
The build detail commit_statuses lists what was posted; commit_url is the commit’s page on the git provider instance your installation is connected to, so it points at a self-hosted GitLab when that is the one in use:
{ "commit_statuses": [ { "repository_id": "…", "repository": "acme-robotics/fleet-worker", "provider": "gitlab", "commit": "9f8e7d6…", "commit_url": "https://gitlab.example.com/acme-robotics/fleet-worker/-/commit/9f8e7d6…", "context": "canopy/build", "state": "failure", "description": "Failed building worker", "target_url": "https://app.canopy.pm/projects/…/pipelines/…", "services": ["worker"], "delivery": "posted", "error": null, "posted_at": "2026-10-08T10:04:00.000Z", "superseded_by_build_id": null } ]}Attach and detach repositories
Section titled “Attach and detach repositories”For setup, attach, branch changes, detach behavior, permissions and API/CLI/SDK examples, see
Multi-repository environments. The Host MCP tools support listing,
attaching and detaching; branch changes are not available as an MCP tool. canopy repositories list without --env
lists repositories from the connected git provider instead of environment attachments.
In the dashboard
Section titled “In the dashboard”The build page has a Sources panel for a build of several repositories: each service with its repository, commit and whether it was built or carried, and the commit statuses with a link to each commit. The release page shows the same pins on the live release and says what each release built. The services list shows the repository and branch of each service once the environment has more than one repository.
Turning the feature off
Section titled “Turning the feature off”A team cannot be removed from host.multi_repository while one of its environments still has a secondary repository;
the answer lists the environments to clean up.