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.
Turning it on for a repository
Section titled “Turning it on for a repository”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.
What runs
Section titled “What runs”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
successwithNo 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: trueindefinePipeline(..., { runOnDraft: true }). - A new commit on the pull request supersedes the runs of the old commit: they are cancelled and their pending statuses become
errorwithSuperseded by <short sha>. Closing or merging cancels the open runs the same way. - A pipeline that fails to compile or cannot start posts
errorwith the reason instead of leaving its status missing.
The statuses
Section titled “The statuses”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.
Making the statuses required
Section titled “Making the statuses required”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.
Trust, secrets and forks
Section titled “Trust, secrets and forks”| 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.
Running again
Section titled “Running again”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.
The run page
Section titled “The run page”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.
From the command line
Section titled “From the command line”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)From the SDK
Section titled “From the SDK”sdk.sourcePullRequestPipelines has setSettings, list, approve and rerun; sdk.pipelineRuns has list and get;
sdk.pipelineSecrets.setPullRequests flips the secret switch. See SDK Reference.
What is not here
Section titled “What is not here”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.