github-review attestor

Reads the pull requests associated with a commit, or one named pull request, and every review on each, from the GitHub REST API, and records them as a point-in-time snapshot.

What it captures

The attestor resolves the repository and commit, picks a token, then reads either GET /repos/{repo}/commits/{sha}/pulls (commit mode) or GET /repos/{repo}/pulls/{pr} (PR mode), and GET /repos/{repo}/pulls/{n}/reviews for each PR. Every list is followed through its Link: rel="next" pages at 100 per page.

Fields (the json tags on Attestor):

• repo: owner/name.
• commit_sha: the commit reviews were looked up for. In PR mode it is the PR's head SHA unless --attestor-github-review-sha is set.
• fetched_at: wall-clock time of the read, RFC 3339 UTC.
• api_base_url: the REST base that was read.
• token_source: which source supplied the token: flag, gh-token-env, github-token-env, gh-auth-token or anonymous. The token itself is never recorded.
• prs[]: number, state (open, closed, or merged when GitHub reports it merged), head_sha, base_sha, url, and reviews[].
• reviews[]: state (GitHub's value, for example APPROVED, CHANGES_REQUESTED, COMMENTED, DISMISSED), user_login, submitted_at, commit_id.

The attestor records reviews as GitHub returns them. It does not decide whether a PR is approved; write that rule in policy.

When to use

To make code review part of the evidence for a release: run it with cilock attest (no wrapped command) after the PR exists, then require APPROVED reviews from the reviewers you trust in a policy. It also works inside cilock run. Auto-detection attaches it when .git/HEAD exists and GITHUB_TOKEN, GH_TOKEN or GITHUB_ACTIONS is set.

Flags

Token precedence: the flag, then GH_TOKEN, then GITHUB_TOKEN, then gh auth token (3-second limit), then anonymous.

Output shape

{
  "repo": "acme/payments",
  "commit_sha": "3f2a9c1...",
  "fetched_at": "2026-10-16T14:02:11Z",
  "api_base_url": "https://api.github.com",
  "token_source": "github-token-env",
  "prs": [
    {
      "number": 42,
      "state": "merged",
      "head_sha": "3f2a9c1...",
      "base_sha": "a81d0e7...",
      "url": "https://github.com/acme/payments/pull/42",
      "reviews": [
        { "state": "APPROVED", "user_login": "alice", "submitted_at": "2026-10-16T13:40:02Z", "commit_id": "3f2a9c1..." }
      ]
    }
  ]
}

Subjects: commitsha:<sha>, repo:<owner/name>, pr:<owner/name>#<number> for each PR, and reviewer:<login> for each reviewer.

Gotchas

• No attestation before the commit reaches GitHub. If GitHub answers 422 "No commit found", the attestor fails and records nothing. An empty prs list would make "every PR is approved" true, so it is never signed for a commit GitHub has not seen.
• A commit in no PR is recorded with prs: []. Your policy must require at least one PR if that matters.
• The snapshot is what the token could see. A private repository read anonymously, or with a token that lacks access, fails with 401, 403 or 404. In GitHub Actions grant pull-requests: read; with a fine-grained PAT grant "Pull requests: Read".
• Anonymous is public-only and limited to 60 requests an hour. The attestor warns when it falls back to anonymous, and warns louder inside GitHub Actions.
• The data is not signed by GitHub. The attestor trusts the API; only cilock's own envelope makes the snapshot tamper-evident, as of fetched_at.
• Each request has a 30-second timeout.

CLI example

# Review state for HEAD of the current checkout
cilock attest -a github-review -k key.pem -o review.bundle.json -s review-head

# One PR, from any directory
cilock attest -a github-review \
  --attestor-github-review-repo aflock-ai/rookery --attestor-github-review-pr 153 \
  -k key.pem -o review-pr153.bundle.json -s review-pr153

See also

• github
• Catalog row