Skip to content

Pipelines on pull requests

Canopy runs the pipelines of a repository on every pull request (GitHub) and merge request (GitLab), reports each as a commit status on the provider, and keeps one run page per pipeline in Canopy. It is the same engine, the same canopy.pipeline.ts and the same steps as a deploy build, with a trust level that keeps pull request code away from what only a reviewed commit may use.

The host.pull_request_pipelines feature is a public preview. It starts off: staff switch it on, and each team opts in. It needs host.pipeline_graph and host.source_pull_requests, because pull requests come from the synchronised pull request rows. A repository then needs the switch below.

A person with source:admin (admin and above) switches pull request pipelines on for a source repository, in the app under the project’s Source section, with canopy source pipelines-config, or with the SDK (sourcePullRequestPipelines.setSettings).

Setting Values Meaning
enabled on, off start pipelines for pull requests of this repository
fork policy deny (default), allow_with_approval what a pull request from a fork may do
definitions from head false (default), true read the pipeline definition from the head of a same-repository pull request instead of its base commit

Turning pipelines off stops new runs. A run that already started finishes and resolves its status, and a pull request that is closed or merged still has its open runs cancelled.

For a pull request, Canopy selects the pipelines of every environment of the team that attaches the repository and builds from the pull request’s base branch, one per build path. The definition is read from the base commit (never from the head, which the author controls), so a pull request cannot change the pipeline that judges it; the only exception is the repository setting above, and only for pull requests from the same repository.

  • A pipeline whose build path has no changed file in the pull request, and none of the paths it watches, does not run. Canopy posts success with No changes under <path> for it only when the branch requires that status; otherwise it posts nothing.
  • A draft pull request runs no pipeline unless the pipeline sets runOnDraft: true in definePipeline(..., { runOnDraft: true }).
  • A new commit on the pull request supersedes the runs of the old commit: they are cancelled and their pending statuses become error with Superseded by <short sha>. Closing or merging cancels the open runs the same way.
  • A pipeline that fails to compile or cannot start posts error with the reason instead of leaving its status missing.

Each pipeline reports the status context canopy/pipeline/<key>, where the key is the pipeline’s build path with every character outside letters, digits, ., _ and - turned into - (root for the repository root). The context is stable: it does not depend on the commit, the attempt or whether the pipeline compiled.

State When
pending the run started, or a fork pipeline waits for an approval
success every step passed, or nothing under the path changed and the branch requires the status
failure a step failed
error cancelled, superseded, timed out, could not start or compile, a fork under the deny policy, or an approval that was not given

A status never hangs. A watchdog every two minutes resolves a run that outlived its two hour deadline (it is cancelled and its status becomes error), an approval nobody gave within seven days, a run that never started, and any pending status that no active run owns. Statuses are posted with the repository’s automation identity and are recorded in Canopy with what was delivered, so a provider outage retries with a growing delay and is abandoned only after ten attempts, visibly.

Required checks are a setting of your provider, which Canopy reads and never writes. Run the pipelines as advisory statuses on the Canopy repository first and make canopy/pipeline/<key> required on the protected branch after about two weeks without a misbehaving status (decision D10 of the release programme). If a status misbehaves, remove it from the required list at the provider: Canopy has no switch that makes a context non-required, and switching pipelines off for the repository stops new runs but does not change what the provider requires.

Pull request Trust level Secrets Platform steps Cache
same repository pull_request only pipeline secrets marked for pull requests removed writes its own namespace, reads it and the shared one, reuses no earlier result
fork, policy allow_with_approval, approved untrusted none removed its own namespace only
fork, policy deny no run - - -

A pipeline secret is available to pull request runs only when marked: canopy pipeline-secrets pull-requests <name> --team <id> --allow, the switch beside each secret under Settings, Organization, Pipeline secrets, or PATCH /teams/{team_id}/pipeline-secrets/{name}. New secrets are unmarked. A step that names an unmarked secret runs without it. The worker checks the mark again when it starts the step, so a plan made earlier cannot hand out a secret that was un-marked since.

A fork pull request under allow_with_approval waits. A person with pipeline:approve_untrusted (developer and above) approves the exact head commit; the approval covers that commit only, and a new push needs a new approval. The approved pipelines run as untrusted: no secret, no platform step, a virtual machine where the team has it enabled. An approval of a commit that is no longer the head is refused with head_changed, and approving twice starts the pipelines once.

canopy source rerun-pipelines, the app’s Run failed pipelines again, or POST .../pipelines/rerun (needs source:review) starts a new attempt of every pipeline of the current commit that failed, errored or was cancelled. The attempt has its own client reference and replaces the status of its context; passed pipelines stay.

Each status links to /pipelines/runs/<run id>: the run of a pipeline that belongs to no environment, with its steps in graph order (status, attempts, cache hit, exit code), the pull request, the attempt, and the statuses it reported with their delivery state. It polls while the run is live. GET /teams/{team_id}/pipeline-runs lists a team’s runs by kind, status or subject and GET /teams/{team_id}/pipeline-runs/{run_id} reads one; an unknown run and another team’s run answer the same empty 404.

canopy source pipelines <number> --repo <id|owner/name> [--team <team_id>] [--head <sha>]
canopy source approve-pipelines <number> --repo <id|owner/name> --head <sha>
canopy source rerun-pipelines <number> --repo <id|owner/name>
canopy source pipelines-config --repo <id|owner/name> [--enable | --disable] [--fork-policy deny|allow_with_approval] [--definitions-from-head true|false]
canopy source runs --team <team_id> [--kind <kind>] [--status running|succeeded|failed|cancelled]
canopy source run <run_id> --team <team_id>
canopy pipeline-secrets pull-requests <name> --team <team_id> (--allow | --forbid)

sdk.sourcePullRequestPipelines has setSettings, list, approve and rerun; sdk.pipelineRuns has list and get; sdk.pipelineSecrets.setPullRequests flips the secret switch. See SDK Reference.

Previews of a pull request are separate: a preview environment deploys pull request code and never satisfies a status, and a release is never published from a pull request run. Release pipelines, consumer updates and the other run kinds use the same run page and POST /v1/pipeline-runs on the executor API; nothing creates them yet.