# CI review check

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](#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:

```yaml
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](/docs/authentication/#tokens) 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:

```yaml
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.
