What is API Contract Governance?
API contract governance is the practice of enforcing rules about how an API contract - its OpenAPI spec - can change: catching breaking changes, checking policy, and deciding whether a change is safe to merge, before it ships.
How is it different from API linting or diffing?
Linting, diffing, and governance answer three different questions. Governance is the one that ends in a decision.
| Practice | Question it answers | Output |
|---|---|---|
| Linting | Is this spec well-formed? | Style and quality warnings on one spec |
| Diffing | What changed? | A list of changes between two versions |
| Governance | Should this change ship? | Risk, policy, and a verdict on whether to allow the merge |
What does governance enforce?
Governance enforces the rules a team agrees on for how its API is allowed to change. The things CodeRifts gates include:
- Breaking-change budgets: how many breaking changes a release is allowed to contain.
- Freeze windows: no risky changes during a release freeze.
- Approval routing: who must sign off before a high-risk change can merge.
- Security and authorization checks: auth downgrades, exposed sensitive fields, and new object-level surfaces.
- Schema-code consistency: the spec change matches the code that actually serves it.
Each rule is a policy the team sets once and the governance layer enforces on every pull request, the same way every time.
When does contract governance happen?
Contract governance acts at the pull request, before the change reaches production. That is the key contrast with gateway and runtime governance, which act after a change is already live.
| Layer | When it acts | What it does |
|---|---|---|
| Contract governance (merge-time) | At the pull request, before deploy | Stops a breaking or non-compliant change from shipping |
| Gateway / runtime governance | At request time, after deploy | Manages what has already shipped: traffic, quotas, access control |
How does CodeRifts do it?
CodeRifts is a zero-config GitHub App that produces a deterministic verdict on every pull request: a 0-100 risk score, an incident cost estimate, a policy decision, and an Ed25519-signed receipt. The decision is one of ALLOW, WARN, REQUIRE_APPROVAL, or BLOCK, and any party can verify the receipt.
It runs three gates:
- Contract gate: breaking API contract changes in the OpenAPI spec.
- MigraGuard: schema migrations that break the live code that serves them.
- AuthDelta: authorization surface changes - new object-level and privileged endpoints.
Because the verdict is deterministic and signed, the same pull request always produces the same decision, and the receipt is an auditable record that the governance rules were applied.