GitHub

Proofroom reads one GitHub organisation with a read-only fine-grained personal access token and files four kinds of evidence. Add the integration on Integrations → Catalogue → GitHub → Connect.

What each collector shows

A pull request counts as approved when a reviewer other than its author has an approval as their latest review submitted before the merge (a later comment does not withdraw it; a later change request or dismissal does). Archived repositories are skipped and counted. Proofroom keeps no pull-request descriptions, review text, commit contents, advisory text or email addresses.

Create the token

1. The token’s owner must be an organisation owner (2FA status of members is visible to owners only), or a security manager if you use only the security-alert collector.
2. In the organisation’s settings, under Personal access tokens, allow fine-grained tokens (and approve the token if your organisation requires approval).
3. On GitHub, Settings → Developer settings → Fine-grained tokens → Generate new token:

   • Resource owner: the organisation.

   • Repository access: All repositories, or the ones you will list in Proofroom.

   • Repository permissions (read-only):

     Permission	Used for
     Metadata	Listing repositories; the rules that apply to a branch (rules/branches)
     Contents	Reading branches
     Pull requests	Merged pull requests and their reviews
     Administration	Classic branch protection and ruleset bypass actors
     Dependabot alerts	Open Dependabot alerts
     Code scanning alerts	Open code-scanning alerts

   • Organization permissions (read-only): Members.

   • An expiry that matches your rotation policy; put a reminder in your calendar to replace it.

4. In Proofroom, enter the organisation login (acme for github.com/acme) and the token. Leave Repositories empty to cover every non-archived repository, or list repository names, one per line. Leave API base URL as https://api.github.com unless you use GitHub Enterprise Server (https://<host>/api/v3; untested).
5. Press Test connection. It confirms the organisation is visible, that every listed repository is visible, and whether the token can read 2FA status (“2FA status needs an organisation owner’s token” means the Members and 2FA collector will fail until the token belongs to an owner).

When a run fails

• “Repository(ies) not visible to the token”: a listed repository is missing from the token’s repository access.
• “ruleset N is not readable; the token needs Administration: read”: the Branch protection collector reads each ruleset’s bypass actors, and GitHub refused (403 or 404). Add the Administration (read) permission to the token. The run fails rather than file “unknown” for who may bypass review.
• “2FA status needs an organisation owner’s token”: the Members and 2FA collector needs an owner’s token.
• “HTTP 403” on Dependabot alerts: the token’s owner is neither an owner nor a security manager, or the token lacks Dependabot alerts read.
• “Code scanning: not enabled, or not visible to this token” in the security-alerts summary: GitHub answers 404 for an organisation without code scanning, and the same 404 for a token whose owner is not an organisation owner or security manager (or for an unknown organisation). Proofroom cannot tell these apart, so the summary says both; if you expect code-scanning alerts, check the token’s owner and the Code scanning alerts permission.
• “Run time budget exhausted”: the organisation is too large for one run; the run is retried an hour later. Narrow Repositories if it keeps happening.

Busy organisations. Merged pull requests reads the pull request lists over REST, then who merged each pull request and its reviews over GraphQL, 25 pull requests per call (a pull request with more than 100 reviews has the rest read over REST). The collector has 30 minutes per run. It works through the window from the oldest merge; if the time runs low it files what it has finished as one evidence item covering the start of the window up to that point (the summary says “Part of the window …”), and the collector is due again at once, so the next run continues from there. A long backlog, such as after months of failed runs, is caught up over several runs rather than failing every time.

GitHub’s rate limits are handled: Proofroom waits and retries when GitHub answers 429, or 403 with Retry-After, and when the primary rate limit is used up (x-ratelimit-remaining: 0) it waits until x-ratelimit-reset if that is within a minute. A limit that resets later fails the run with “rate limited until ”; the run is retried automatically (1 hour, then 6 hours, then 24 hours after the failures). GitHub’s secondary limit (403 or 429) without a Retry-After is waited out for a minute. GraphQL’s own rate limit (HTTP 200 with an error of type RATE_LIMITED) is treated the same way, waiting until x-ratelimit-reset; any other GraphQL error fails the run.