Skip to content

Pull requests in Canopy Source

Canopy keeps the pull requests (GitHub) and merge requests (GitLab) of a repository you connected, shows what the provider shows (changes, commits, checks, reviews, discussion) and lets you merge, close, comment and review from Canopy with your own provider access. It adds one thing the providers do not: a merge gate that states, check by check, why a merge is or is not allowed.

The host.source_pull_requests feature is a public preview. It starts off: staff switch it on, and each team opts in. While it is off the routes answer 403 with error: feature_disabled. It needs host.source.

Pull requests are kept per source repository: one row for a provider repository however many environments attach it. A person with source:admin (admin and above) switches synchronisation on for a repository, in the app under the project’s Source section, with canopy through the API, or with the SDK (sourceRepositories.setPullRequestSync).

Canopy reads the repository’s pull requests with the automation identity bound to it (a team clone identity registered with --purpose automation, see Team Clone Identities). Without one, sync stays on but nothing is read and the repository shows identity_missing as the reason. A webhook delivery re-reads one pull request within a minute; a reconcile every ten minutes re-reads open pull requests nobody touched for 30 minutes and lists the first page of every enabled repository once an hour, so a dropped webhook still shows up. A pull request missing from a list is never closed because of that: only reading it directly closes a row.

Action Needs Acts with
List and read pull requests, files, commits, checks, reviews, the gate source:read and your own provider access to the repository your provider link or GitHub App installation
Comment, approve, ask for changes source:review (developer and above) your provider credential
Merge, close source:merge (developer and above) your provider credential
Turn synchronisation on or off, bind the automation identity source:admin (admin and above) none

Canopy stores pull request rows, but it serves them only after your own provider access to the repository has been shown (cached for ten minutes per person and repository). The automation identity syncs and writes for Canopy-authored pull requests; it never lets a person see what their own provider access would not. Files, patches, commits, reviews and discussion are not stored: they are read live with your credential.

A repository that no environment has attached answers 422 repository_not_attached for these reads, because Canopy has no way to read it as you.

Every check is pass, fail or unknown, and unknown is never eligible.

Check Rule
open, not_draft the provider’s state
head_fresh every check was read at the provider’s current commit
canopy_checks_pass every Canopy check selected for the pull request passed on this commit
required_checks_pass every check the branch requires passed on this commit; unreadable requirements are unknown
no_failing_checks no reported check failed; a running one is unknown
approvals, no_changes_requested the provider’s approvals are satisfied and nobody asked for changes; a provider that cannot say (GitLab without approval rules) is unknown
mergeable no conflicts; the provider still working it out is unknown
method_allowed the repository allows the method
actor_can_write the person (or identity) can write
not_bypass_actor automation only: the identity is not a rule bypass actor
origin rules per origin of the pull request, see below

A check reported for another commit is shown (for_older_commit) and never counted. The gate shown on a pull request is the latest stored evaluation, labelled with the commit it judged and its age; one for another commit, or older than 30 minutes, is stale and never eligible. A merge always evaluates again at the provider’s current commit; POST .../refresh evaluates without merging. Canopy never uses admin bypass, never edits branch protection, never dismisses reviews and never approves its own pull requests.

origin says what created a pull request, and is set only when Canopy created and recorded it, never from a branch name: external (everything else), release, consumer_update, security, configuration, infrastructure_pin. A security fix is held to the Security Bot being on, a branch Canopy created, a verification of this exact commit no older than seven days and the tracked commit; an infrastructure pin is never merged by automation; a release or dependency update without its policy facts is unknown and so never eligible.

Writes answer 202 with an action and an operation (GET /teams/{team_id}/operations/{operation_id} shows its status, and GET /source/repositories/{id}/pulls/{number}/actions/{action_id} its result). The worker does the work.

Merge needs expected_head_sha, the full commit you looked at. A stored head that differs is refused at once with 409 head_changed and the current head; otherwise the worker reads the pull request at the provider, evaluates the gate again and merges only when every check passes and the provider’s head is still that commit. The provider’s answer is never taken as proof: Canopy reads the pull request back, so a lost response still ends as merged, and an answer that cannot be confirmed ends as unconfirmed. Every attempt is recorded with the gate it saw (merged, ineligible, head_changed, not_mergeable, forbidden, capability_unsupported, unconfirmed, error), and every request is an audit event (source_pull_request.merge_requested and the others).

Provider Merge methods Request changes Merge at an expected head
GitHub merge, squash, rebase yes yes
GitLab merge, squash, rebase no (capability_unsupported) yes
Bitbucket not supported no no

A project with the feature on has a Source section: the repositories of the project with their sync state, each repository’s pull requests by state, and a workspace per pull request with Overview (the gate, links, attempts), Files (generated files folded, a partial list says “Showing N of M”), Commits, Checks and Discussion. Merge shows the exact commit and sends it as the expected head; it is disabled while the gate is not satisfied and absent without source:merge. An environment with the feature on has a Pull requests section under Source: the open pull requests into the branch it builds.

canopy source prs --repo <id|owner/name> [--team <team_id>] [--state open|closed|merged|all] [--origin <origin>] [--author <login>] [--base <branch>]
canopy source pr <number> --repo <id|owner/name> [--team <team_id>]
canopy source merge <number> --repo <id|owner/name> --expected-head <sha> [--method merge|squash|rebase] [--wait]
canopy source close <number> --repo <id|owner/name> [--wait]
canopy source review <number> --repo <id|owner/name> (--approve | --request-changes <body> | --comment <body>) [--wait]

Name a repository by its source repository id, or by owner/name with --team. --wait polls the operation for up to two minutes; a failed merge prints the gate checks that stopped it and exits non-zero.

sdk.sourcePullRequests has list, get, files, filePatch, commits, checks, reviews, discussions, gate, getAction, refresh, merge, close, comment, review and listForEnvironment; sdk.sourceRepositories has setPullRequestSync. See SDK Reference.

Pull request pipelines and their check contexts are described in Pipelines on pull requests. Release trains, dependency update pull requests and environment adoption are planned phases of the same programme; their origins exist in the model but nothing creates them yet.

Security fixes are linked: a pull request that a recorded remediation opened is origin: security, the gate holds it to the Security Bot, branch, verification and tracked-commit rules above, and merge attempts made before this feature were copied into the merge attempts. The Security page merges through this gate: POST .../security/remediations/{id}/merge creates a merge action and answers 202, and the older eligibility check no longer exists. It answered as this gate does in every case but one, which the shared decision table pins: a branch ruleset that cannot be read stops this gate, while the older check treated it as no rule.

When the environment is set up to run Renovate in patch-only mode (SECURITY_RENOVATE_PATCH_IMAGE), the run reads the repository with a read-only credential, prints the files it changed as a patch set, and Canopy writes the branch and the pull request itself through the same provider layer; the Security Bot then needs no write token for that repository.