The GitHub App is the zero-setup enforcement path. Install it on a GitHub organisation, pick the repositories, and PolicyCodex evaluates every pull request server-side — posting a native PolicyCodex check run with findings annotated in the diff. No workflow file, no CI minutes, nothing to add to any repository. The App also checks pushes to the default branch (so anything that merges past an advisory check is still recorded against main) and scans the repositories it can see, which is what fills the inventory side of Reporting → Scope.

​
App or Action?

GitHub App

Install once, covers every selected repository. PolicyCodex runs the evaluation. Configuration lives in PolicyCodex. No API key needed — the App authenticates as itself.

GitHub Action

Per-repository workflow file. Runs on your CI minutes, configuration in the repo, works from any CI via the REST API. Needs an API key. See GitHub Action.
Both paths run the same compliance evaluation and write the same check and violation records — Reporting → Scope shows which path covers each repository. They can coexist; a repository with the Action keeps working unchanged after the App is installed.

​
Installing

You need two hats (or two people): an organisation admin on GitHub to install the App, and a domain owner in PolicyCodex to connect it.
1

Install the App on your GitHub organisation

From Settings → Integrations, click Connect GitHub… — it opens the App’s installation page on GitHub. Choose the organisation, then select All repositories or a specific set. The repositories you select here are exactly the ones PolicyCodex can see and check.
2

Let the redirect connect the installation

After installing, GitHub redirects you back to PolicyCodex Settings with the installation ID attached, and the connection is claimed automatically. You’ll see the connected state with the GitHub account name.
Connecting is domain-owner-only, and one installation is linked per organisation. If the redirect can’t reach you (for example a local development instance), paste the Installation ID from GitHub’s confirmation page into the manual field instead.
3

Scan the repositories

Go to Reporting → Scope and click Rescan repos. The inventory fills with every repository the App can see, classified as covered or not.
4

Verify with a pull request

Open (or push to) any pull request in an installed repository. A PolicyCodex check run appears on the PR — no workflow involved. A compliant change completes green; violations of enforced MUST statements fail the check, annotate the diff, and post a findings comment in the conversation.
Settings → Integrations showing the Connect GitHub button and the manual installation ID field

​
What the App is allowed to do

The permissions requested at install time, and why:
No GitHub tokens are ever stored. PolicyCodex keeps only the installation ID — which is useless without the App’s private key. Each evaluation mints a fresh installation token that expires within the hour. Uninstalling the App from GitHub disconnects the integration and removes the scanned inventory automatically.

​
What runs when

Pull requests

Opened, updated, or reopened (draft PRs are skipped): the diff and repository file listing are evaluated against your enforced statements. Enforced MUST violations fail the check; SHOULD findings warn in the summary.

Default-branch pushes

Every push to the default branch is checked the same way, and the verdict is attached to the commit. On plans where the check can’t be made merge-blocking, nothing lands unnoticed.
Findings appear in three places: the check run’s summary (with statement slugs linked to their RFCs), inline annotations on the offending lines, and — for PRs with findings — a single sticky comment that updates on each push and rewrites itself to Resolved once a later run is clean. Compliant PRs get a green check and no comment.

​
Blocking merges

The check fails on enforced MUST violations, but whether a failing check prevents merging is a GitHub setting: add PolicyCodex as a required status check in branch protection (or a ruleset) on the repositories you want gated.
GitHub only offers required status checks on public repositories or on paid plans (GitHub Pro / Team / Enterprise). On a free-plan private repository the check is advisory — visibly red, recorded in PolicyCodex, but the merge button stays enabled.

​
Troubleshooting

Check the App’s Recent Deliveries page (GitHub App settings → Advanced). No deliveries at all: the webhook is inactive or the Pull request event isn’t subscribed. Deliveries failing: the endpoint or secret is misconfigured. Deliveries OK but no check: confirm the repository is in the installation’s selected set and that the installation is connected in Settings → Integrations.
The evaluation errored — most often the organisation’s LLM configuration (Settings → LLM) is missing, invalid, or the configured model is returning malformed output. The check never fails silently: an infrastructure error is always visible as neutral, not reported as a pass.
When the App’s permissions change, GitHub asks each installed organisation to approve the update (organisation Settings → GitHub Apps). Until approved, features needing the new permission — like the findings comment — log an error and skip.
The scan only sees the installation’s selected repositories. Add repositories from the App’s page on GitHub (Configure → Repository access), then Rescan repos on Reporting → Scope.