Multi-repository environments
An environment normally builds every service from one repository. With multi-repository support an environment keeps
its primary repository and can attach more, so that for example web and api come from one repository and worker
from another. A push to one repository builds only the services of that repository whose folder it touched; the other
services keep running the images of the current release.
It sits behind the host.multi_repository platform feature, which is generally available and enabled by default;
while staff have it switched off, the environment repository API answers 403 with error: feature_disabled.
GitHub, GitLab and Bitbucket repositories are supported. Reading a repository uses the team’s
clone identity.
Attach a repository
Section titled “Attach a repository”POST /environments/{environment_id}/repositories{ "repository": "acme/worker", "provider": "github", "branch": "main" }Needs project:blueprint (admin and above). repository is a provider path: owner/name on GitHub,
group/project (subgroups allowed) on GitLab, or workspace/slug on Bitbucket. A URL, a .git suffix, an empty or
.. segment is refused with 422 and error_code: invalid_repository. branch defaults to the environment’s
branch.
Canopy then, in this order:
- mints a read credential from the team’s clone identity for the repository’s owner and checks that the repository is
readable and the branch exists. Failures answer
422withidentity_missing(the team has no clone identity for that owner),identity_expired,repository_not_in_scope,repository_not_accessibleorbranch_not_found, and502withprovider_unavailable; - registers the push webhook of the new repository through your connected git provider (a clone identity only
reads), with its own URL and its own signing secret. Without a connected provider the answer is
422provider_not_connected; a provider that refuses the webhook answers502webhook_registration_failedand the repository is not attached.
201 returns the repository:
{ "repository": { "id": "…", "environment_id": "…", "url": "acme/worker", "provider": "github", "branch": "main", "is_primary": false, "is_active": true, "webhook_registered": true, "created_at": "2027-08-09T10:00:00Z"} }webhook_registered is true when Canopy registered a per-repository webhook and holds its secret; it is false for a
GitHub App connection, whose deliveries arrive at the App level. created_at is null for rows that predate the column.
The webhook secret is never returned.
A repository can be attached once per environment (409 repository_already_attached, the comparison ignores case),
the primary repository counts, and an environment holds at most 10 repositories (409 too_many_repositories).
The Host SDK exposes the same environment-scoped operations. Start with the authenticated client from the SDK reference:
const repositories = await sdk.environments.repositories.list(environmentId);const attached = await sdk.environments.repositories.attach(environmentId, { repository: "acme/worker", provider: "github",});await sdk.environments.repositories.update(environmentId, attached.id, { branch: "release" });await sdk.environments.repositories.detach(environmentId, attached.id);The Host MCP server also exposes tools to list, attach and detach environment repositories. It does not expose branch changes; see the MCP reference for tool names and input fields. MCP tool availability does not grant access: the API still enforces team membership, feature availability and permissions.
List, change the branch, detach
Section titled “List, change the branch, detach”GET /environments/{environment_id}/repositories -> { "repositories": [ … ] } (primary first)PATCH /environments/{environment_id}/repositories/{repository_id} { "branch": "release" }DELETE /environments/{environment_id}/repositories/{repository_id}[?force=true]Listing needs environment:read. Changing the branch checks it through the clone identity first; the primary
repository follows the environment’s branch and answers 409 primary_repository.
Detaching removes the repository’s webhook at the provider, checks that it is gone, and deactivates the row. It is
refused with 409 repository_in_use while a service still builds from the repository, and for the primary repository.
If the webhook cannot be removed the call fails with 502 webhook_deregistration_failed and the repository stays
attached; force=true detaches anyway and reports webhook: { "status": "failed", "error": "…" } in the answer so the
leftover webhook can be removed by hand. A successful call returns { "repository": { … }, "webhook": { "status": "deregistered" | "not_found" } }. Attaching the same repository again creates a new row with a new webhook.
In the app
Section titled “In the app”With the feature on, an environment has a Repositories page under Configure. It lists the repositories the environment builds from, the primary one first, with each one’s provider, branch, whether Canopy registered a webhook and the services that build from it. An admin can attach a repository (path, provider and optional branch), change the branch of a secondary repository and detach it. Attach failures show the reason in words (a missing or expired clone identity, a repository outside every identity’s scope, a branch that does not exist, an unreachable provider or a webhook the provider refused). Detaching a repository a service still uses lists those services. Only when the provider webhook could not be removed does the dialog offer Detach anyway, which leaves the webhook behind. Without the feature, or when the team has not opted in, the page says so and offers nothing.
Point a service at a repository
Section titled “Point a service at a repository”PATCH /environments/{environment_id}/app-services/{service_id} { "source": { "repository_id": "…" } }POST /environments/{environment_id}/app-services { "name": "worker", "kind": "worker", "source": { "repository_id": "…" } }From the CLI, canopy app-services create and update take --repository <owner/name> [--provider github|gitlab|bitbucket]:
the CLI finds the attached repository in the environment’s list and sends its id, and refuses a repository that is not
attached with the canopy repositories attach command to run first. canopy app-services apply --file ... --repository <owner/name> sets the source of every service in the file that has none (a service may also carry its own "repository"),
and canopy blueprint plan --service <node> --repository <owner/name> moves a Blueprint service. See the
CLI reference.
repository_id must be an active repository of the same environment (422 repository_not_found); null means the
primary repository. The default service stays on the primary repository (409 primary_source_change) and an image
service has no repository (422 source_kind_mismatch). While the feature is off for the team the request is refused as
before with multi_repository_unsupported.
Apply, proposals, Blueprint and templates
Section titled “Apply, proposals, Blueprint and templates”The same source is accepted wherever services are written, with the feature on for the team:
- Apply (
POST /environments/{environment_id}/app-services/apply): each service ofservicesmay carrysource: { "repository_id": "…" }(or the top-levelrepository_id). Everything is validated before anything is written, in one query for the whole list: an unknown, detached or foreign repository answers422 repository_not_foundnaming the service (services[2]), an image service422 source_kind_mismatch, and a first service (it takes over the default one) on a repository other than the primary409 primary_source_change. Applying a proposal uses this route, so a proposal made for an attached repository is applied with that repository’s id. - Blueprint (
derive,plan,apply): a service node names its repository assource.repository(providerandpath, e.g.owner/name), not an id, so a document can be read from one environment and planned against another.derivereads the repository and branch from each service’s own row.planlooks the repository up among the repositories attached to the environment (path without regard to case, provider when both sides name one) and puts its id in theservice.create/service.updateoperation. A repository that is not attached is a plan error,repository_not_attached, with afixthat says how to attach it; planning never attaches a repository and calls no provider. A node’sbranchmust be the branch of its repository (branch_override_unsupported), and services of one repository that name different branches arebranch_conflict. A plan turns stale (blueprint_state_changed) when a repository is attached or detached after it was made. With the feature off a node from another repository ismulti_repository_unsupported, as before. - Templates (
POST /projects/{project_id}/deploy-template): a template whose services build from several repositories is deployed as one environment. The first service built from source decides the primary repository; every other repository is attached to the new environment with the branch of its first service (or that service’s override) and its services are put on it. It needsproject:blueprinton top ofenvironment:create, a connected GitHub or GitLab account (its webhook is registered with it) and a team clone identity covering the repository. Services of one secondary repository must name the same branch (template_not_deployableotherwise). Without the feature the template is refused withtemplate_not_deployable, as before. The attachment happens while the environment is being set up: a repository that cannot be attached fails the setup and the reason is on the environment’sdeploy_error; the repositories attached so far stay attached.
Which GitHub App installation clones a repository
Section titled “Which GitHub App installation clones a repository”A user can have the Canopy GitHub App installed on several accounts and organisations. For a build, a .canopy.yml
read or a preview, Canopy uses the installation whose account is the repository’s owner, and clones with a token
limited to that one repository (contents: read). It no longer takes the first installation of the user. When no
installation belongs to the owner, Canopy does not borrow another account’s: it falls back to the user’s OAuth
connection, as it does for GitLab. An account whose installation row has no recorded account login keeps working only
while it is the user’s single installation.
How a push is matched
Section titled “How a push is matched”A push arrives on the webhook of one repository row and is matched against that row only:
| Situation | Decision |
|---|---|
| The delivery id was seen before for this row | skipped_duplicate |
| The row is secondary, a service builds from it, and the team does not have the feature | skipped_flag_disabled |
| The row was detached | skipped_repository_inactive |
| The row is secondary and no service builds from it | skipped_no_services |
| The pushed branch is not the row’s branch (the environment’s branch for the primary row) | skipped_branch |
The environment’s deploy trigger is external_ci |
skipped_external_ci |
No service of this row has a touched file under its source_path |
skipped_path |
| Otherwise | accepted: the services whose path was touched are built at the pushed commit |
A service at the repository root is affected by any push. The delivery ledger (GET /environments/{id}/webhooks/deliveries) shows the decision, and for skipped_path the services and their paths.
Pushes to two repositories within a build window are merged into one release that holds both new commits.
An environment with a single repository, or with the feature off, keeps its previous behaviour: every service folder counts, and a push builds the environment.
Delivery ids
Section titled “Delivery ids”A delivery that carries GitHub’s X-GitHub-Delivery or GitLab’s X-Gitlab-Event-UUID is recorded under that id for
the row. A redelivery of the same id is not processed again and is recorded as skipped_duplicate. This applies to
every environment. A delivery without the header is handled as before.
Previews
Section titled “Previews”A pull or merge request on any repository of the environment gets a preview of the whole environment: the services built from that repository run from the pull request head, and every other service runs the image of the environment’s active release. No other repository is cloned, so a pull request never causes a sibling repository to be read with anyone’s credentials, and a fork pull request never uses the team clone identity at all.
Previews are off until you turn them on for the environment: canopy previews settings --env <environment_id> --enable (or the MCP tool host_preview_settings). Turning them on subscribes every repository of the environment to pull and merge request events with that repository’s own provider. canopy previews settings --env <environment_id> shows the time to live, the number of previews allowed at once and the fork policy; --ttl-hours, --max-concurrent and --fork-policy change them. A preview’s builds belong to the preview, not to the environment, so canopy builds show cannot read them: canopy previews build <preview_id> --env <environment_id> prints the preview’s current build (--build <build_id> for another one) with its status, failure and Forest lifecycle, from GET /environments/{environment_id}/previews/{preview_id}/builds/{build_id}.
| Situation | Decision recorded |
|---|---|
| The pull request targets a branch other than the row’s branch (the environment’s branch for the primary row) | skipped_preview_branch |
| The row is secondary and the team does not have the feature | skipped_flag_disabled |
| The row was detached | skipped_repository_inactive |
| No service that runs in a preview builds from the row | skipped_no_services |
| The environment has no active release, or the release lacks the image of a service the preview would carry | skipped_preview_no_release (detail.reason is no_active_release or services_not_released, with the service_ids) |
| More services than a preview may run, counting the carried ones | skipped_preview_too_many_services |
| Otherwise | accepted_preview_provision, accepted_preview_refresh or accepted_preview_destroy |
- Two pull requests with the same number on two repositories are two previews. Pull requests of different repositories are never combined into one preview.
- Closing the pull request destroys the preview whatever the feature or the release say by then: every workload of the preview goes, and the builds stay as history. The release is not touched.
- A preview created while the feature was on is rejected (
destroy_reason:feature_disabled,repository_detached,no_services,no_active_releaseorservices_not_released) when its job runs after the situation changed; a refresh in that situation marks the previewfailedwith the reason. - The reconcile sweep applies the same rules per repository: a missed pull request is provisioned against its own row and branch, and a closed one is destroyed.
- The status of a preview is posted on the pull request’s own repository. For a pull request on a secondary repository
of a team with the feature, Canopy uses the team’s clone identity with the
statuspurpose; it falls back to the account that last deployed when the team has no identity for the repository. A fork pull request always uses the latter. Thecanopy/buildbuild statuses above are never posted for a preview. - The configuration file (
.canopy.yml) of a service built from the pull request’s repository is read from the pull request branch; the file of a carried service is read at the commit its image was built from, through the account that last deployed, and is ignored when that account cannot read the repository.
An environment with a single repository, or with the feature off, keeps its previous behaviour: every service of the
preview is built from the pull request branch. With the feature off, a pull request on a secondary repository is
recorded as skipped_flag_disabled and creates nothing.
Turning the feature off
Section titled “Turning the feature off”Turning host.multi_repository off is refused (409 multi_repository_in_use) while an environment of the team has a
secondary repository, including when the attach is racing the opt-out: both take the same lock. Detach the
repositories first.