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.

Start here

Three things people arrive wanting to do. Each card names the page that answers it, and the scope that page states for itself.

Everything each capability does — and does not — is listed under Capabilities.

Run it — for operators

You already installed it. These are the pages you need when you are the one on call for it.

Incident and compliance material lives in the Trust Center.

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. See the Platform truth table — what actually enforces, where and What each proof proves — and what it does not.

BLOCK remediation transaction — what re-submission means

Endpoint criticality weight — surface outsized downstream impact

Deploy gate — advisory reporting and opt-in enforcement

Enforcement status — see reporting and prevention posture

MCP poison-risk assessment — flag risky tools for review

Execution attestations — CAS and remediation-loop proofs, and their limits

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:

Decision Model (Decision Spec 2.0)

CodeRifts uses a mode-discriminated union to categorize results. The primary branch is the analysis_outcome, which classifies the risk detected under the supplied evidence (analyze mode — informational, never permission).

On authorize responses only, the execution_action drives the control flow (analyze responses omit this field entirely):

The risk_score (0–100) continues to be reported as a composite metric of the change's impact, but is no longer the primary branching logic. For the full technical contract, see the Decision Spec 2.0 documentation.

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
• policy.freeze_hard_block— boolean, default false: during a freeze window a breaking change returns BLOCK instead of REQUIRE_APPROVAL
• policy.freeze_on_risk_score_hard_block— boolean, default false: a risk-score freeze returns BLOCK instead of REQUIRE_APPROVAL

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.

Accepted keys (measured from the running App's parser): the reference below was read out of the production parser, not invented. Anything not listed is loaded by YAML but ignored — do not document extra keys as accepted.

Document (top-level)

rules[] entry

When several rules trigger, the strictest action wins: block > require_approval > warn > allow. Keys such as policy.dry_run, schedule and approvers are not validated by the parser — their behavior is intentionally left undocumented here.

Condition forms

A condition is accepted only if its first token is one of: endpoint_removed, risk_score, breaking_changes, omega_api, reflex_override. Two forms evaluate:

• Boolean, exact whole string: endpoint_removed or reflex_override alone
• Numeric comparison: FIELD OP NUMBER with >= <= > < == !=, e.g. risk_score >= 80

Minimal valid example

version: 1
rules:
  - id: block-endpoint-removal
    condition: endpoint_removed
    action: block
  - id: warn-high-risk
    condition: risk_score >= 80
    action: warn
policy:
  default_action: block

Do not invent condition strings or actions beyond the tables above — 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).

Test a policy before committing

The policy simulator dry-runs a policy document against a hypothetical change without touching a pull request. Use it to test a policy document before committing it.

Endpoint: https://app.coderifts.com/api/v1/policy-simulator. An API key is required. The accepted policy keys are the ones in the reference above.

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:

Capabilities

Every shipped capability page, in one place. Each states what it does and where it stops — link text is each page’s own title and first heading, not a summary written here.

Report vs prevent

• What each path does — and does not
• Platform truth table — what actually enforces, where
• What each proof proves — and what it does not

Gates and outcomes

• Deploy Gate — Deploy gating reports by default. Enforcement is opt-in.
• Enforcement Status — See where your posture reports — and where it prevents.
• Remediation Transaction — A BLOCK is not a dead end.

Proofs and signals

• Execution Attestations — CAS attestation and remediation-loop attestation
• Endpoint Criticality Weight — See the changed endpoints with outsized downstream impact.
• MCP Poison-Risk Assessment — Flag MCP tools that deserve review.

Agent surface

• Agent Onboarding — From keyless discovery to receipt-gated governance
• Agent Contract Lockfile — Lock the observed agent-contract surface.
• Execution Proof — A final answer can carry its own execution proof.

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.