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.
Turning it on for a repository
Section titled “Turning it on for a repository”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.
Who can see and do what
Section titled “Who can see and do what”| 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.
The merge gate
Section titled “The merge gate”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.
Origins
Section titled “Origins”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.
Acting on a pull request
Section titled “Acting on a pull request”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 |
In the app
Section titled “In the app”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.
From the command line
Section titled “From the command line”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.
From the SDK
Section titled “From the SDK”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.
What is not here yet
Section titled “What is not here yet”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.