The Precedent handbook
GitHub Actions
The check-decisions Action comments on each pull request with the decisions that apply to the Areas it touches. It fails the check only on recorded facts: an expired exception in a checked Area, or a superseded decision the pull request cites.
1. Add the repository
Precedent has to know the repository before it can check its pull requests. Ask your assistant in the repository to set Precedent up, or add the repository under Repositories. The check then uses the Areas the repository follows in Precedent. No file has to be committed.
A repository with a version 2 .precedent.json keeps working on a pull_request workflow that checks it out: the check uses the file's Areas until the repository is recorded. While a workflow uses Action v3 or earlier, the assistant keeps a version 2 file. On the recommended workflow below, add the repository first. Version 1 files are not read.
In a version 2 file, checkAreaIds names the one to three Areas to check, and the check ignores recordAreaId. By default every pull request is checked against those Areas. To check only the Areas a change touches, add a paths list mapping globs to Area ids. Copy an id from For integrations at the bottom of the Area's page in Precedent, which people with Member access or higher on the Area and workspace administrators see, or ask your assistant for list_areas:
{
"version": 2,
"deployment": "https://app.example.com",
"workspaceId": "…",
"recordAreaId": "…",
"checkAreaIds": ["<Platform Area id>"],
"paths": [
{ "glob": "services/inspection/**", "areaId": "<Inspection Area id>" },
{ "glob": "services/search/**", "areaId": "<Search Area id>" }
]
}Each changed file counts toward every Area whose glob it matches. A file that matches no glob counts toward checkAreaIds. ** matches across directories, * within one, and a glob without a slash, such as *.tf, matches a file name at any depth.
2. Create a CI token
In Precedent, open Settings, Your preferences and choose Create CI token under Pull request checks. Copy the token; it is shown once and stored hashed. By default it can check any Area you can see. Choose one Area to limit it: it then checks and cites only that Area's decisions, and a project whose checkAreaIds or paths name another Area is refused with a message saying so.
The token is read only and lasts 365 days. It acts as you and sees exactly what your assistant would see: restricted Areas you are not in never appear in a comment. It works only for the pull request check: assistant tools refuse it, so a leaked secret cannot read decision text. It is listed under Connected assistants as Pull request check, with each check logged as a pr_check call, and you or a workspace administrator can revoke it there. Nothing rotates, so any number of runs and repositories can share one token. Create one per repository if you want to revoke them separately.
3. Add the workflow
Add the repository first: this workflow does not read .precedent.json, so for a repository that is not recorded the check stops with a message saying so.
Store the token as the PRECEDENT_TOKEN repository secret, then save as .github/workflows/precedent.yml:
name: precedent
on:
pull_request_target:
types: [opened, edited, synchronize, reopened]
permissions:
contents: read
pull-requests: write
id-token: write
jobs:
decisions:
runs-on: ubuntu-latest
steps:
- uses: Imgntech/check-decisions@v4
with:
token: ${{ secrets.PRECEDENT_TOKEN }}To pin the Action, use the commit SHA of a release in place of @v4.
The edited type reruns the check when the description changes, so citing a different decision updates the result. Make the decisions job a required status check in the branch rules if a failure should block merging.
The check compares the Precedent section at the pull request's head commit, so a branch made before the section was last updated on your default branch shows it as out of date until the branch is brought up to date.
pull_request_target, from your default branch, so a pull request cannot change the check that runs on it. The check reads the pull request through GitHub's API and never runs its code. Do not add a checkout step or any step that runs the pull request's code: the job holds your CI token. Anyone who can open a pull request starts a run. On a public repository the comment names only decisions in the Areas the repository follows.Proved repositories
A check that sends a GitHub Actions OIDC token in the X-Precedent-OIDC header proves which repository it runs in. GitHub issues the token only to a workflow with the id-token: write permission, and the token is GitHub's signed statement of the repository's id, owner and visibility. Precedent checks the signature against GitHub's published keys, then uses the Areas the repository follows in Precedent, whatever the pull request's files say. If the repository is not recorded in Precedent, a check on a pull_request workflow uses the Areas in .precedent.json and says so.
For a public repository, the check counts and does not list two kinds of decision: decisions in restricted Areas, and cited decisions outside the Areas the repository follows. A decision that is not listed never fails the check. Action v4 sends the token when the workflow has the id-token: write permission; Action v3 does not.
What the comment shows
The Action posts one comment and edits it on every run, so a pull request never collects duplicates. It lists, with links to Precedent:
- The facts that fail the check, each with its reason and, for a superseded decision, the decision that superseded it.
- The decision refs the title, description and commits mention, such as AR-041, with their state. Text that only looks like a ref is ignored unless it matches a decision in the workspace.
- The decided decisions tagged with the checked Areas, with Expired and Expiring badges first. An exception is expiring when its date is within 14 days. The list shows 50; the rest are counted.
- Other recorded facts: an overdue review, or a current decision that still depends on a superseded one.
Only refs, titles, Types, states, dates, links and a digest of the Precedent section leave Precedent. Summaries, rationale and evidence stay in the workspace. The same text is written to the job summary.
What fails the check
| fail-on value | Fails when | To clear it |
|---|---|---|
expired-exception | A decided exception tagged with a checked Area is past its date. In Acme Robotics, AR-118 kept raw inspection images for 30 days and expired; AR-097 applies again. | The owner reaffirms the exception with a new date, or records a replacement. Then rerun the check. |
superseded-ref | The pull request cites a superseded decision. A description citing AR-014, which AR-051 superseded, fails and names AR-051. | Cite the successor instead and edit the description, or record a new decision. |
Both fail by default. Set fail-on to one of them, or to an empty string to comment without failing. Nothing else fails the check: search similarity, expiring exceptions and overdue reviews are informational. A failed run also writes an error annotation per fact.
Precedent section
If the repository's AGENTS.md or CLAUDE.md has a Precedent section, the check compares it with Precedent and says so in its comment: current; out of date, when a decision has changed since it was written; edited by hand, when the text between the markers was changed; or not compared, when it could not be. None of these fails the check. Ask your assistant to update the section. The comment also says when a section's markers are damaged or a file could not be read.
Inputs
| Input | Default | Purpose |
|---|---|---|
token | The CI token. Required. | |
oidc | true | Send GitHub's identity token so Precedent can verify the repository. Needs the id-token: write permission. |
url | the deployment in .precedent.json, or https://precedent.biz | The Precedent deployment. |
config | .precedent.json | Path to .precedent.json, for a repository that keeps one. Ignored on pull_request_target. |
fail-on | expired-exception,superseded-ref | The facts that fail the check. |
comment | true | Set to false to report in the job summary only. |
github-token | github.token | Reads the pull request and writes the comment. The default is the workflow's own token, which needs the pull-requests: write permission. A personal token also works. A GitHub App token cannot find its earlier comment and posts a new one each run. |
The endpoint
With no .precedent.json or a version 3 file, the Action calls two authenticated endpoints, GET /api/pr-check/project and GET /api/pr-check, which need GitHub's identity token. With a version 2 file it calls the endpoint below. From another CI system, call it with the Area ids yourself:
curl -sf "$PRECEDENT_URL/api/w/$WORKSPACE_ID/pr-check?nodeIds=$AREA_ID&refs=AR-014,AR-118" \ -H "Authorization: Bearer $PRECEDENT_TOKEN"
The path takes the workspace id or slug. nodeIds lists up to 20 Area ids and defaults to the token's Area when it is limited to one. refs lists up to 500 refs to look up; strings that are not this workspace's refs are ignored. The response holds repository, areasSource, areas, decisions, cited, failures, withheld, notices, warnings and section. When the check used the repository's record, areasSource is repository and repository names it; otherwise areasSource is request and repository is null. withheld is the number of decisions counted and not listed, and notices holds the messages the comment shows, such as an Area that was skipped.
sectionAreaIds lists up to 53 Area ids; send every Area of the project when the repository has a Precedent section. section then holds the digest of the section Precedent writes for those Areas, or a problem saying why there is none. Ids that are missing, archived or restricted are left out without an error, and only the first 20 that remain are used. A token limited to one Area gets a problem, not a 403, and the 403 and 404 below apply to nodeIds only. Without sectionAreaIds, section is null.
| Status | Meaning |
|---|---|
| 400 | An Area id in nodeIds or sectionAreaIds is not a valid id, a list is too long, or a token that is not limited to one Area names no Area. On /api/pr-check and /api/pr-check/project, also: the X-Precedent-OIDC header is missing, or the repository is not recorded in this workspace. |
| 401 | No CI token, the CI token is invalid, expired or revoked, or the GitHub Actions OIDC token could not be verified. |
| 403 | The CI token belongs to another workspace, is limited to another Area, or the workspace's trial has ended. |
| 404 | An Area id does not exist or the token cannot see it. A typo is reported, not checked as an empty Area. For a proved repository, an Area the token cannot see is skipped with a notice instead. |
| 429 | The CI token's rate limit, per minute. |
| 503 | Precedent could not reach GitHub to verify the OIDC token, or is briefly unavailable. Rerun the check. |