The Action is where governance becomes enforcement. It checks a pull request’s diff against your enforced statements, posts findings as a review, and fails the check when a MUST is violated.
If you want zero per-repository setup, install the GitHub App instead — it runs the same evaluation server-side with no workflow file and no API key. The Action is the right choice when you want the configuration in the repository, the compute on your own runners, or a non-GitHub CI via the REST API.

​
Setup

1

Issue an API key

Settings → API keys. Name it after the repository so you can revoke it individually. The key is shown once — copy it now.
2

Validate the key

Before burying it in a secret, prove it works and is scoped to the organisation you expect:
A JSON array of statements means the key is live; 401 means it was mistyped or deleted. Keys are organisation-scoped — if the statements returned aren’t the corpus you expect, you’re holding a key from the wrong organisation.
3

Store it as a secret

In the repository (or organisation) settings, add it as POLICYCODEX_API_KEY.
4

Add the workflow

Commit the file below to .github/workflows/policycodex.yml on your default branch.
.github/workflows/policycodex.yml
fetch-depth: 0 matters — the Action needs the merge base to compute the diff. With a shallow clone it sees the wrong changes, or none.
pull-requests: write is required to post the review.

​
Inputs

​
Scoping to a domain

Scope deliberately, and say why in a comment. A repository silently checked against one domain looks compliant while most of your corpus never touches it — see Reporting → Scope.

​
What it does on each run

1

Fetches enforced statements

For the configured domains.
2

Evaluates the diff

Posts the change to check_compliance, along with the repository file listing so missing-file requirements are checkable.
3

Posts a review

One comment per finding: the statement text, its slug, and the severity.
4

Sets the check result

Fails if any finding maps to an enforced MUST. SHOULD findings warn only.
5

Records the outcome

Violations are written back to PolicyCodex, and the run reports to Reporting → Scope whether it passed or failed.

​
Pass and fail

Fails the check

A finding against an enforced MUST or MUST NOT.

Warns only

SHOULD and SHOULD NOT findings, and everything from RFCs still at approved.
This is the lifecycle doing its job: a standard at approved produces the same comments without blocking anyone, so teams see the work coming before it becomes mandatory.

​
Rolling it out

Add the Action while your standards are still at approved. Everyone sees the findings; nobody is blocked. Promote once the noise is manageable.
Run it on a repository whose team is on side. Fix the false positives at the RFC before ten teams meet them.
Add it to branch protection only after enforcement is genuinely intended.
It tells you which repositories are really running it. Adoption you cannot see is adoption you do not have.

​
Troubleshooting

The key is missing, wrong, or was deleted. Check the secret name matches the workflow, and check the key’s last-used column in Settings.
Most often the RFC is still at approved rather than enforced, or the domain input is scoping it away. Check the LLM is configured too — see Settings → LLM.
The Action is not reaching the API. Check api-base-url and the key. A workflow that only exists on a feature branch also never runs on subsequent PRs.
Usually a shallow clone. Confirm fetch-depth: 0.