Skip to content

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.

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.

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-token
canopy clone-identities rotate <identity_id> --team <team_id> --expires-at <iso8601> --token-file ./bitbucket-token
canopy 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-token
canopy 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.

@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.

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.

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.

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.

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.

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 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.

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.

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, with contents, pull_requests, statuses and checks write. The installation must have those permissions granted; an installation that has not accepted them answers repository_not_in_scope on the mint.
  • GitLab. Register a project or group access token with the api scope and the Developer or Maintainer role, with purpose: 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).