Report Proofline's pull-request review from a CI job with proofline ci review, and let the job's exit code follow the result. A GitHub Actions job needs no stored secret.
What the command reports#
proofline ci review waits for the pull-request review of the commit the job tests, prints it and exits with a code the job can act on. It reads the newest pull-request review whose head is exactly that commit. A deployment review of the same commit is not used.
The command requests no review. The Proofline GitHub App starts the review when the commit is the head of an open pull request, and the command waits for that review to appear and finish. The one exception is a GitHub Actions job on a pull request with no review, such as a draft.
The commit is --commit, else the COMMIT_SHA environment variable, else the GitHub Actions job's commit. On a pull-request event that is the pull request's head, because GITHUB_SHA names GitHub's merge commit there; on any other event it is GITHUB_SHA. The command accepts only a full commit SHA and refuses a branch name. The repository is --repo owner/name, else the checkout's Git remote.
The output is text. Add --json for JSON.
GitHub Actions#
Give the job id-token: write and set no PROOFLINE_TOKEN. The CLI asks the runner for an OpenID Connect (OIDC) token and exchanges it with Proofline for a token that reads only that repository's reviews and expires after one hour. The job needs no organization ID.
This job reports the review of a pull request and uploads the findings to code scanning:
on: pull_request
permissions:
contents: read
id-token: write
security-events: write
jobs:
proofline:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: curl -fsSL https://proofline.sh/cli | sh
- id: review
continue-on-error: true
run: |
~/.local/bin/proofline ci review --sarif proofline.sarif
- if: always() && hashFiles('proofline.sarif') != ''
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: proofline.sarif
continue-on-error keeps the job advisory: the review is reported, and its exit code does not fail the workflow.
Proofline issues the token only when all of these hold:
- The repository is enabled in a GitHub App installation connected to an active Proofline organization.
- The person whose action started the run is a Proofline user and a member of that organization. A run started by anyone else is refused.
- The organization's API token policy allows
reviews:read, and any allowed address ranges it sets include the runner's address.
When Proofline refuses the exchange, or the runner issues no OIDC token, the command exits 1. A refusal does not say which condition failed. If the pull request's head moved after the job started, the command exits 1 and asks you to rerun the job.
A pull request with no review#
On a pull_request event, a job that authenticates with OIDC and finds no review of its head after two minutes requests one review of that head. The usual case is a draft pull request, which the App does not review unless your organization or repository reviews drafts. The person who started the run needs write access to the repository on GitHub, and the organization's API token policy must allow reviews:request. When the request is refused, the command prints the reason and keeps waiting until its deadline.
Jobs that use PROOFLINE_TOKEN, push jobs and jobs on other events request no review. A push to a branch with no pull request has no pull-request review to report.
Other CI runners#
On any other runner, set PROOFLINE_TOKEN and PROOFLINE_ORGANIZATION_ID. An organization token with the reviews:read scope, restricted to the repository, is enough; Authentication explains how to create one. Keep it in the runner's secret manager. When PROOFLINE_TOKEN is set in GitHub Actions, the CLI uses it instead of the OIDC exchange.
A Cloud Build step on a pull-request trigger:
steps:
- id: proofline
name: debian:stable-slim
entrypoint: bash
args:
- -c
- |
apt-get update -qq && apt-get install -y -qq curl ca-certificates
curl -fsSL https://proofline.sh/cli | PROOFLINE_INSTALL_DIR=/usr/local/bin sh
proofline ci review --repo "$REPO_FULL_NAME" --sarif proofline.sarif
env:
- COMMIT_SHA=$COMMIT_SHA
- REPO_FULL_NAME=$REPO_FULL_NAME
- PROOFLINE_ORGANIZATION_ID=<organization ID>
secretEnv: [PROOFLINE_TOKEN]
allowFailure: true
availableSecrets:
secretManager:
- versionName: projects/<project>/secrets/proofline-token/versions/latest
env: PROOFLINE_TOKEN
allowFailure keeps the step advisory, as continue-on-error does in GitHub Actions.
Options#
| Option | What it does |
|---|---|
--fail-on warning or --fail-on serious | Exits 3 when the completed review has an open finding at or above that severity |
--sarif FILE | Also writes the review to FILE as SARIF 2.1.0 once a review is found |
--timeout MINUTES | Sets how long the command waits for the review to appear and finish; the default is 30 minutes |
Without --fail-on, a completed review exits 0 even when it has findings, because pull-request reviews are advisory. --fail-on is the job's own threshold. A finding that someone dismissed or accepted as a risk does not count toward it; a finding whose dismissal or acceptance has expired counts again. The flag changes neither the --json output nor the SARIF file.
A review still running at the deadline prints its link. The SARIF file of a review that did not complete in time records executionSuccessful as false.
Exit codes#
| Exit | Meaning |
|---|---|
| 0 | The review completed, with no open finding at or above --fail-on when that flag is set |
| 1 | A usage, authentication or authorization error |
| 2 | The review ended without a complete result; the output names each gap |
| 3 | The review completed with an open finding at or above --fail-on |
| 4 | Proofline was unreachable or failed, no finished review existed by the deadline, or --fail-on had no open-finding counts to read |
Exits 2 and 4 are never a pass. A review that did not finish exits 2 or 4 whatever it found, because its findings are not its whole result. To fail a build on findings, pass --fail-on and remove continue-on-error or allowFailure; exits 2 and 4 then fail the build too, because an unknown result is not a pass.
Exit 0 reports that the review completed and that no open finding reached the job's threshold. It does not establish that the change has no risk.