Quick Start

Prefer to ask instead of read? The docs are queryable by agents via MCP — see Agents.

Install the GitHub App

Go to github.com/apps/coderifts and click Install. Choose which repositories to enable.

Open a pull request

Open a pull request that modifies an OpenAPI spec file.

Review the report

CodeRifts automatically posts a governance report as a PR comment.

That's it. No config file needed. No CI setup. No API keys. See the live demo PR at github.com/coderifts/demo/pull/4 for what a report looks like.

Make the check block a merge#

Quick Start gives you a report (a PR comment and a check run). This section is what turns that report into a gate — a team can stop after Quick Start and use CodeRifts for visibility only.

If you want the check to stop a merge, all four of the following must hold. Missing any one of them leaves you with a green or advisory check that does not protect the branch.

1. Require the status check in branch protection

For your base branch (e.g. main). The context name is CodeRifts — API Contract Check — an em dash (U+2014) between "CodeRifts" and "API", not a hyphen; a typed - will never match.

If missing: a red CodeRifts check is advisory only — GitHub still allows the merge. You may also see CodeRifts / contract-gate on the same PRs: that is an additional advisory check and does not block merges today — do not require it as your gate.

2. Bind the check to the CodeRifts GitHub App

app_id: 2860592. Name-only matching is not enough: with app_id: null, any writer with repository write access can post a success status under that context name and satisfy the requirement.

gh api \
  --method PUT \
  -H "Accept: application/vnd.github+json" \
  /repos/OWNER/REPO/branches/main/protection/required_status_checks \
  -f strict=true \
  --input -

If missing: the gate is a decoration — a forged or accidental success status unblocks the merge while the App's real check may still be red or pending.

3. Ship a schema CodeRifts can analyse

OpenAPI/Swagger on a discovered path, or paths listed in .coderifts.yml.

If missing: the check completes neutral. GitHub treats neutral as non-blocking, so a required check can stay green while inspecting nothing.

4. Include administrators in branch protection

enforce_admins, if admins must not bypass the gate.

If missing: repository admins can merge past a red required check.

Reporting without these steps is a valid setup. Add them only when you want CodeRifts to be a merge gate, not only a PR report. For a full breakdown of which integration paths actually prevent a call vs. only report, see What Each Path Does.

What gets analyzed#

CodeRifts triggers automatically when a pull request modifies files matching these patterns:

Pattern	Example
`*/openapi.yaml`	`openapi.yaml`, `api/openapi-v2.yaml`
`*/openapi.json`	`openapi.json`, `docs/openapi-spec.json`
`*/swagger.yaml`	`swagger.yaml`, `api/swagger-v1.yaml`
`*/swagger.json`	`swagger.json`

Custom patterns can be defined in .coderifts.yml using the schema or spec_patterns fields.

Supported formats#

OpenAPI 2.0 (Swagger)
OpenAPI 3.0
OpenAPI 3.1
Both YAML and JSON

See the full configuration reference and PR report breakdown on Configuration & Reports.

Updated Aug 15, 2026