Skip to content

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.

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:

  1. 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 422 with identity_missing (the team has no clone identity for that owner), identity_expired, repository_not_in_scope, repository_not_accessible or branch_not_found, and 502 with provider_unavailable;
  2. 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 422 provider_not_connected; a provider that refuses the webhook answers 502 webhook_registration_failed and 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.

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.

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.

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.

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 of services may carry source: { "repository_id": "…" } (or the top-level repository_id). Everything is validated before anything is written, in one query for the whole list: an unknown, detached or foreign repository answers 422 repository_not_found naming the service (services[2]), an image service 422 source_kind_mismatch, and a first service (it takes over the default one) on a repository other than the primary 409 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 as source.repository (provider and path, e.g. owner/name), not an id, so a document can be read from one environment and planned against another. derive reads the repository and branch from each service’s own row. plan looks 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 the service.create / service.update operation. A repository that is not attached is a plan error, repository_not_attached, with a fix that says how to attach it; planning never attaches a repository and calls no provider. A node’s branch must be the branch of its repository (branch_override_unsupported), and services of one repository that name different branches are branch_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 is multi_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 needs project:blueprint on top of environment: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_deployable otherwise). Without the feature the template is refused with template_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’s deploy_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.

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.

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.

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_release or services_not_released) when its job runs after the situation changed; a refresh in that situation marks the preview failed with 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 status purpose; 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. The canopy/build build 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 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.