Documentation

Everything you need to get started with CodeRifts — from one-click install to full configuration reference.

Prefer to ask instead of read? Our docs are queryable by agents via MCP - see the Agents page.

Quick Start

Get CodeRifts running in 30 seconds:

Want to see what a report looks like? Check the live demo PR.

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. They are different things: a team can stop after Quick Start and use CodeRifts for visibility only. For the same honesty across every path (runtime guard, contract-gate, MCP tools, CLI), see What each path does — and does not.

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.

gh api \
  --method PUT \
  -H "Accept: application/vnd.github+json" \
  /repos/OWNER/REPO/branches/main/protection/required_status_checks \
  -f strict=true \
  --input - <<'EOF'
{
  "strict": true,
  "checks": [
    {
      "context": "CodeRifts — API Contract Check",
      "app_id": 2860592
    }
  ]
}
EOF

What Gets Analyzed

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

You can also define custom patterns in .coderifts.yml using the schema or spec_patterns fields (see Configuration).

Supported Formats

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

Understanding the Report

Every PR comment from CodeRifts includes several sections. Here's what each one means:

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 (when risk scoring is enabled)
• 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 (see also Two policy mechanisms):

• 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.)
• CORS or rate-limit configuration changes

Semver Suggestion

Recommends a semantic version bump based on the changes detected:

• MAJOR — breaking changes found
• MINOR — new endpoints or fields added (backward-compatible)
• PATCH — documentation or metadata changes only

API Changelog

An auto-generated changelog grouped by: breaking, added, changed, and deprecated. Copy-paste ready for your release notes.

See all of these sections in action on the live demo PR.

Two policy mechanisms

CodeRifts ships two different policy files. They use different paths and different syntax. They do not replace each other. The first thing to learn is which file you are editing — and which one can stop a merge.

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

This is the repository config file already described in the Configuration Reference below. 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 on this site for governance-style rules include (non-exhaustive; see the full example under Configuration):

• 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. That is not restated here — use 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.

What it does with the outcome: annotation only — it contributes to what you read on the pull request. It does not replace analyzer policy and does not, by itself, fail the required status check or block a merge.

Syntax on this site: this repository has not previously documented the accepted keys for api-policy.yaml. Do not invent a full schema here. The structural shape in production is a versioned document with a rules list of condition / action entries (file path .github/api-policy.yaml). For exact condition strings and actions, treat the running App as source of truth until a full reference is published — a wrong copy-paste example is worse than none.

Do not confuse it with the homepage “Governance as code” snippet if you have seen a rules: / condition: / action: block labeled as .coderifts.yml — that labeling is wrong. Analyzer policy for merge-relevant blocking lives in .coderifts.yml under policy (and related keys in the Configuration Reference).

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. For how this file differs from .github/api-policy.yaml, see Two policy mechanisms first.

# .coderifts.yml — Full Configuration Reference
# All settings are optional. CodeRifts works without this file.

# ─── Schema Paths ─────────────────────────────────────────────
# Explicit paths to your OpenAPI spec files.
# If omitted, CodeRifts auto-discovers using default glob patterns.
schema:
  - openapi/api.yaml
  - docs/swagger.json

# Custom glob patterns for spec file discovery (optional)
spec_patterns:
  - "**/api-spec*.yaml"
  - "docs/openapi/**"

# ─── Breaking Change Budget ───────────────────────────────────
# Maximum allowed breaking changes per PR (default: unlimited)
breaking_budget: 3

# Fail the GitHub check when breaking changes are found (default: true)
fail_on_breaking: true

# ─── Policy Rules ─────────────────────────────────────────────
policy:
  # Paths where endpoint deletion is blocked
  no_delete: ["/payments/*", "/auth/*"]

  # Block deletion of required fields
  no_delete_required_fields: true

  # Require deprecation before removal
  require_deprecation_before_removal: true

  # Freeze window — block breaking changes during this period
  freeze:
    start: "2026-03-01"
    end: "2026-03-15"
    reason: "Q1 release freeze"

  # Require semver bump when breaking changes are detected
  require_version_bump: true

  # Auto-trigger freeze when risk score exceeds threshold (0-100)
  freeze_on_risk_score: 80

# ─── Domain Ownership ─────────────────────────────────────────
# Map API paths to teams for accurate risk scoring
domains:
  - name: payments
    paths: ["/payments/*"]
    owners: ["@payments-team"]
    sensitivity: critical

  - name: users
    paths: ["/users/*", "/auth/*"]
    owners: ["@platform-team"]
    sensitivity: high

# ─── Security Analysis ────────────────────────────────────────
security:
  # Additional patterns to flag as sensitive (regex)
  sensitive_patterns: ["ssn", "tax_id", "passport"]
  # Fail the check on critical security findings
  fail_on_critical: true

# ─── Notifications ────────────────────────────────────────────
# Send alerts to Slack and/or Microsoft Teams
notifications:
  on: breaking          # Options: breaking (default), all, high_risk
  slack:
    webhook_url: "https://hooks.slack.com/services/..."
  teams:
    webhook_url: "https://outlook.office.com/webhook/..."
  mute:                 # Repos to exclude from notifications
    - "internal-tools"

# ─── Schema Overlap Detection ─────────────────────────────────
# Warn when other open PRs modify the same spec files (Pro only)
overlap_detection: true
overlap_ignore_branches:
  - "dependabot/*"
  - "renovate/*"

# ─── Risk Scoring Weights ─────────────────────────────────────
# Customize the weight of each risk dimension (must sum to 1.0)
risk_weights:
  revenue_impact: 0.3
  blast_radius: 0.3
  compatibility: 0.2
  security: 0.2

# ─── Comment Mode ─────────────────────────────────────────────
# "full" shows all sections inline; "summary" collapses details
comment_mode: full

# ─── Fun Mode ─────────────────────────────────────────────────
# Adds a haiku to the PR comment based on the analysis
fun_mode: true

Option Reference

Delivery Channels

CodeRifts is available through 4 channels. Choose the one that fits your workflow:

FAQ

Does CodeRifts read my source code?

No. CodeRifts only reads OpenAPI spec files (YAML/JSON). It does not access, analyze, or store your application source code, tests, or any other files.

What permissions does it need?

Is it free?

Yes. The Free tier includes unlimited public repositories and up to 3 private repositories. All Pro features (risk scoring, governance, security analysis, deprecation enforcement) are included free during the beta. See pricing.

What happens if my spec file is not in the root directory?

CodeRifts auto-discovers spec files using glob patterns that search all directories. If your file is at api/v2/openapi.yaml, it will be found automatically. You can also configure explicit paths in .coderifts.yml:

schema:
  - api/v2/openapi.yaml
  - docs/swagger.json

Can I use it with GitLab or Bitbucket?

The GitHub App is GitHub-only. However, the REST API and CLI work with any Git platform. You can integrate them into GitLab CI, Bitbucket Pipelines, or any CI/CD system.

How do I disable it for a specific PR?

Add [skip coderifts] to the PR title. CodeRifts will skip the analysis entirely for that PR.

Where is the API Reference?

The interactive API reference (Swagger UI) is available at app.coderifts.com/api/docs.