Documentation

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

Quick Start

Get CodeRifts running in 30 seconds:

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

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 policies configured 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

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.

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 — 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.