Understanding the report

Risk score (0–100)#

An overall risk assessment based on 4 dimensions:

Scores map to grades: A (0–19), B (20–39), C (40–59), D (60–79), F (80–100).

Breaking changes table#

Lists every breaking change detected, including the change type (endpoint removed, field type changed, required field added, etc.), the affected endpoint and path, a risk label per change, and a lifecycle label showing whether the element is new, deprecated, or removed.

Policy violations#

If you have analyzer policies in .coderifts.yml, this section shows which rules were violated:

• Endpoint deletion blocked — no_delete paths were removed
• Breaking budget exceeded — more breaking changes than breaking_budget allows
• Freeze window active — breaking changes during a configured freeze period
• Version bump required — breaking changes without a semver bump in the spec
• Unsafe migration gated — MigraGuard (opt-in) reads database migration files and the source references they touch, in memory and never persisted, and blocks a destructive migration before it merges

Security analysis#

Scans for security-sensitive changes: authentication scheme changes, new endpoints without security definitions, sensitive field exposure (passwords, tokens, SSNs, etc.), and CORS or rate-limit configuration changes.

Semver suggestion#

Recommends a semantic version bump based on the changes detected: MAJOR for breaking changes, MINOR for new endpoints or fields (backward-compatible), PATCH for documentation or metadata changes only.

API changelog#

An auto-generated changelog grouped by breaking, added, changed, and deprecated — copy-paste ready for release notes.

Two policy mechanisms#

CodeRifts ships two different policy files. They use different paths and different syntax, and they do not replace each other.

1. .coderifts.yml — analyzer policy (can fail the check)#

Policy lives under the policy object (and related top-level keys such as breaking_budget / fail_on_breaking). The analyzer evaluates it when scoring a PR; blocking violations show up as Policy Violations in the comment and can fail the GitHub check.

Keys documented for governance-style rules include (non-exhaustive):

• breaking_budget — max breaking changes allowed per PR
• fail_on_breaking — whether breaking changes fail the check
• policy.no_delete — path patterns where endpoint deletion is blocked
• policy.no_delete_required_fields
• policy.require_deprecation_before_removal
• policy.freeze — start / end / reason freeze window
• policy.require_version_bump
• policy.freeze_on_risk_score

Important: failing the check only stops a merge when branch protection is set up correctly — see Make the Check Block a Merge.

2. .github/api-policy.yaml — comment policy DSL (does not stop a merge)#

A second file, under .github/, not the repo root. It is a separate DSL, not the policy: object in .coderifts.yml. The webhook path loads it and uses the result when building the PR comment — annotation only, it does not fail the required status check or block a merge by itself.

The structural shape in production is a versioned document with a rules list of condition / action entries. For exact condition strings and actions, treat the running App as source of truth — a wrong copy-paste example is worse than none.

Configuration reference#

All settings are optional. CodeRifts works without a config file. To customize behavior, create a .coderifts.yml file in the root of your repository:

# .coderifts.yml — optional configuration
spec:
  path: "api/openapi.yaml"      # default: auto-detect
rules:
  breaking-changes: error        # error | warn | off
  naming-convention: warn        # camelCase enforcement
  deprecation-policy: warn       # require sunset headers
notifications:
  slack:
    webhook: $SLACK_WEBHOOK_URL
    on: [breaking-change, security]