Team clone identities
A clone identity is the credential a team gives Canopy to read its repositories and, for commit statuses, to write to them. It belongs to the team, not to the person who pushed. Canopy selects an identity for each repository based on its provider and scope, so a multi-repository build can use different identities for different repositories.
This is a preview surface. It sits behind the host.multi_repository platform feature, which is off by default, and the
team must have opted in. It also depends on Forest and Host environment services. Otherwise every route answers 403
with error: feature_disabled. A build clones the secondary
repositories of an environment with these identities, and attaching one reads it with them (see
Multi-repository environments). These routes register and manage the identities. See multi-repository environments for how builds and commit statuses use them.
All routes need the team:manage action (admin and above). A member of another team gets 404.
Providers
Section titled “Providers”GitHub. Register an installation of the Canopy GitHub App that you have connected to your account. The
installation’s account (organisation or user login) becomes the identity’s scope. Nothing is stored: for every build,
Canopy asks GitHub for an installation token limited to the single repository being cloned, with contents: read, and
statuses: write as well when it posts a commit status. The token expires with GitHub’s own expiry (at most one hour)
and is never stored.
GitLab. Create a read-only project or group access token in GitLab and register it. Give it the read_api and read_repository scopes: Canopy checks that a repository exists through GitLab’s project API, which read_repository alone cannot call (the attach would answer that the repository does not exist or the identity cannot read it). scope is the group or project
path the token was issued for, for example acme or acme/app. The token covers a repository only when the repository
path equals the scope or sits below it: acme/app does not cover acme/app-secrets. If several tokens cover a
repository the most specific one is used, and an expired one is skipped in favour of a wider one. The token is
encrypted at rest with a key of its own, wrapped by the same Vault Transit key (with the local fallback outside
production) that protects environment variables, and it is never returned by any route, log or audit event. Declare
status_write: true only for a token that may also post commit statuses (GitLab needs the api scope for that).
Bitbucket Cloud. Create a workspace access token with repository read access and register the workspace name as
scope (for example, acme). Repository-level and project-level tokens are not accepted. The token must have an
expiry date. Set status_write: true only when it also has permission to post commit statuses. Bitbucket tokens are
encrypted and never returned. They can be rotated like GitLab tokens, but Bitbucket identities cannot be used by the
Security Bot for remediation.
From the CLI and MCP
Section titled “From the CLI and MCP”canopy clone-identities list --team <team_id> [--include-revoked]canopy clone-identities register --team <team_id> --provider github --installation-id <id>canopy clone-identities register --team <team_id> --provider gitlab --scope acme/platform \ --expires-at 2027-03-01T00:00:00Z --token-file ./gitlab-token [--rotation-remind-at <iso8601>] [--status-write]canopy clone-identities register --team <team_id> --provider bitbucket --scope acme \ --expires-at 2027-03-01T00:00:00Z --token-file ./bitbucket-token [--rotation-remind-at <iso8601>] [--status-write]canopy clone-identities rotate <identity_id> --team <team_id> --expires-at <iso8601> --token-file ./gitlab-tokencanopy clone-identities rotate <identity_id> --team <team_id> --expires-at <iso8601> --token-file ./bitbucket-tokencanopy clone-identities revoke <identity_id> --team <team_id>canopy clone-identities register --team <team_id> --provider gitlab --scope acme/app --purpose automation \ --expires-at 2027-03-01T00:00:00Z --token-file ./gitlab-project-tokencanopy clone-identities bind <identity_id> --repository <source_repository_id>canopy clone-identities unbind --repository <source_repository_id>The commands mirror the routes below one to one, behind the same host.multi_repository feature, and print the identity
as the API returns it (--json) or one line per identity. A GitLab token is never an argument, so it cannot end up in
shell history or a process list: give it as --token-file <path> or pipe it with --token-stdin, for example
pass show gitlab/acme | canopy clone-identities rotate ... --token-stdin. The token is trimmed of a trailing newline,
sent once and never printed. Rotation supports GitLab and Bitbucket; GitHub credentials are minted per build and cannot
be rotated. An agent can read identities (never a secret) with the read-only MCP tool host_list_clone_identities;
registering, rotating and revoking are not available over MCP.
Use the Host SDK
Section titled “Use the Host SDK”@canopy/sdk exposes cloneIdentities.list(), register(), rotate(), and revoke(). The API key needs the
team:manage action for the team. This example registers a GitHub App installation already connected to the caller’s
account:
import { createCanopySDK } from '@canopy/sdk';
const sdk = createCanopySDK({ apiKey: process.env.CANOPY_API_KEY });const teamId = process.env.CANOPY_TEAM_ID!;const identities = await sdk.cloneIdentities.list(teamId);const identity = await sdk.cloneIdentities.register(teamId, { provider: 'github', installationId: 123456,});console.log(identities.length, identity.scope);The SDK’s GitLab and Bitbucket registration inputs accept the token as secret; read it from a secret manager or
protected environment variable and never log it. Canopy stores it encrypted and does not return it. The SDK resource
returns identity fields in the API’s snake_case response shape.
Register
Section titled “Register”POST /teams/{team_id}/clone-identities{ "provider": "github", "installation_id": 123456 }POST /teams/{team_id}/clone-identities{ "provider": "gitlab", "scope": "acme/platform", "secret": "glpat-...", "expires_at": "2027-03-01T00:00:00Z", "rotation_remind_at": "2027-02-15T00:00:00Z", "status_write": false}For a Bitbucket Cloud workspace token, use the workspace name as scope and
include the token expiry:
{ "provider": "bitbucket", "scope": "acme", "secret": "<workspace-access-token>", "expires_at": "2027-03-01T00:00:00Z", "status_write": false}201 returns { "identity": { ... } }. expires_at is required for GitLab and optional for GitHub;
rotation_remind_at defaults to 14 days before expires_at. A team has one active identity per provider and scope:
a second registration answers 409 with error_code: identity_exists. A GitHub installation that is not connected to
your account answers 422 with installation_not_found.
GET /teams/{team_id}/clone-identities[?include_revoked=true]Returns { "identities": [ ... ] }, newest first, with id, provider, kind, scope, github_installation_id,
status_write, expires_at, rotation_remind_at, last_used_at, created_by, revoked_at, created_at and two
flags: expires_soon (from rotation_remind_at until expiry) and expired. There is never a secret in the answer.
Rotate
Section titled “Rotate”POST /teams/{team_id}/clone-identities/{id}/rotate{ "secret": "glpat-...", "expires_at": "2027-09-01T00:00:00Z" }Replaces the stored token and expiry of a GitLab or Bitbucket identity in one write and re-arms its reminder. A build that already
read the old token finishes with it. GitHub identities answer 409 with rotation_not_applicable, a revoked identity
409 with identity_revoked.
Revoke
Section titled “Revoke”DELETE /teams/{team_id}/clone-identities/{id}Marks the identity revoked and erases its stored token. The next build that needs it fails with identity_missing.
Revoking twice is harmless. A GitHub installation is not uninstalled.
Expiry reminders
Section titled “Expiry reminders”An identity with an expiry raises one notification to the team when it reaches its rotation_remind_at, and one more
after each rotation that sets a new expiry. A scheduled check runs every six hours.
Every registration, rotation, revocation and every credential minted for a build is a host audit event
(clone_identity.registered, .rotated, .revoked, .minted). A minted event records the identity, team,
repository, purpose (build or status) and build id, never the credential. If the event cannot be written, no
credential is issued.
Failures a build can report
Section titled “Failures a build can report”identity_missing (no active identity for the provider, or none able to write statuses), repository_not_in_scope
(identities exist but none covers the repository, or GitHub refused the repository), identity_expired,
provider_unavailable.
Turning the feature off
Section titled “Turning the feature off”Turning host.multi_repository off for a team is refused with 409 and error_code: multi_repository_in_use while an
environment of the team still has a secondary repository. The answer lists the environments to clean up in
environments, with the full count in total.
In the dashboard
Section titled “In the dashboard”Git access in the team’s navigation (shown once multi-repository environments are on for the team) lists the team’s identities with whether each is active, about to expire or expired, what it can do and when it was last used. A GitHub App installation you have connected is registered with one choice; a GitLab token takes its group or project path, the token and its expiry date, and says whether it may also post commit statuses. A GitLab token can be replaced before it expires, and any identity can be revoked after a confirmation. Secrets are encrypted and never shown again.
Automation identities
Section titled “Automation identities”Canopy automation (release pull requests, dependency update pull requests and the commit statuses on them) never uses a
person’s credential. It uses a clone identity registered with purpose: automation and bound to one source repository.
The purpose is separate from build and remediation: an automation identity cannot clone for a build, and a build
identity cannot be bound for automation. Bitbucket cannot have one.
- GitHub. Register the App installation with
purpose: automation. For each use Canopy asks GitHub for a token limited to the one repository, withcontents,pull_requests,statusesandcheckswrite. The installation must have those permissions granted; an installation that has not accepted them answersrepository_not_in_scopeon the mint. - GitLab. Register a project or group access token with the
apiscope and the Developer or Maintainer role, withpurpose: automation. It is stored encrypted like any other GitLab identity and is rotated the same way.
Registering an identity does not make it usable. Bind it to the repository it serves:
PUT /source/repositories/{source_repository_id}/automation-identity{ "identity_id": "<clone identity id>" }The identity must belong to the same team and provider, must not be revoked or expired, and its scope must cover the
repository (422 with identity_not_automation, identity_provider_mismatch or identity_scope_mismatch, 409 with
identity_revoked or identity_expired). Binding needs source:admin (admin and above) and is audited as
source_repository.automation_bound; DELETE on the same path unbinds it (source_repository.automation_unbound).
A repository with no bound identity mints nothing for automation (identity_missing, reason
automation_identity_unbound); a revoked bound identity says automation_identity_revoked. Find the source repository
id with GET /source/repositories?team_id=<team_id> (see Canopy Source).