Skip to main content
coderifts Install on GitHub

Two policy files. Two jobs.

One can fail a check. The other writes a PR comment. The keys below were read from the running App parser on 2026-09-14, not copied from an older page.

The two files

They are not aliases. Mixing them up is how a team thinks it blocked a merge and only posted a comment.

.coderifts.yml

Repo root. Parsed by the app's configuration parser (parseConfig). The webhook analyzer reads it. It can fail the check (fail_on_breaking, freeze, required-field rules).

.github/api-policy.yaml

Fetched by the webhook after the check run is already completed. Parsed by the app's YAML policy reader (parsePolicy / evaluateYamlPolicy). It only feeds the PR comment (and a forensic field on the receipt). It does not change the check conclusion.

Measured: completeCheckRun runs, then yaml-policy is evaluated. A block action in api-policy.yaml cannot turn a green check red.

What parsePolicy accepts

This is the load-bearing list. It was re-measured on 2026-09-14 by calling parsePolicy against the shipped policy reader, not by copying a harvest.

  • version must be the number 1. A string "1" is rejected (version !== 1). Measured: valid: false, error Unsupported policy version: 1 (expected 1) — the printed 1 is the string.
  • rules[] required, non-empty. Each rule needs id, condition, action.
  • action one of block, require_approval, warn, allow.
  • Action priority when several rules fire: block > require_approval > warn > allow (ACTION_PRIORITY 4 / 3 / 2 / 1).
  • The first token of condition must be one of: endpoint_removed · risk_score · breaking_changes · omega_api · reflex_override. Anything else is unknown condition field.
  • policy.default_action is validated if present (same four actions). Other policy.* keys are not.

Not validated — present keys are ignored or applied without a schema check:

  • policy.dry_run — read later as a boolean in evaluateYamlPolicy. parsePolicy does not check it. A policy with dry_run: true still returns valid: true. And so does a typo. Measured 2026-09-15 against the running parser: dryrun, dry-run — and banana — all return valid: true with no error and no warning. No key under policy: is checked against a schema, so a misspelled switch is accepted exactly like a correct one, and is ignored exactly the same way. If you rely on dry_run, spell it right and verify the behaviour — the validator will not tell you.
  • schedule — not a policy-level field in the validator. Evaluation looks at rule.schedule (an array of start/end strings). Invalid windows are not rejected at parse time.
  • approvers — copied through on a matched rule if present. Never type-checked.
version: 1
rules:
  - id: no-endpoint-removal
    condition: endpoint_removed
    action: block
  - id: high-risk
    condition: risk_score >= 80
    action: require_approval
policy:
  default_action: allow

What parseConfig reads from .coderifts.yml

Measured by calling parseConfig on 2026-09-14. Names that appeared in an older docs harvest and are not keys here are listed at the bottom — the parser wins.

Top-level keys the function returns

schema · contract_artifacts · fail_on_breaking (exported as failOnBreaking) · ignore · policy · policy_pin · domains · app_versions · approval_matrix · freeze_periods · notify · docs_paths · fun_mode · comment_mode · comment_debug · risk_scoring · security · linting · flags · reviews · notifications · overlap_detection · overlap_ignore_branches · generator_detection · confidence_threshold · exceptions · cost · dependencies · generator_drift · migraguard · actionguard

policy object (defaults)

  • require_deprecation_before_removal: false
  • no_delete_endpoints: false
  • no_delete_required_fields: false
  • max_breaking_changes: null
  • require_version_bump_on_breaking: false
  • freeze_on_risk_score: null
  • freeze_hard_block: false
  • freeze_on_risk_score_hard_block: false
  • require_source_binding: false
  • require_completeness: "none"
  • require_fingerprint_rebind: false

Turning require_deprecation_before_removal on does not find a removal.

freeze_periods is an array of { start, end, reason }. Entries without valid dates are skipped. reason becomes "" if omitted.

Harvest names that the parser does not have (09-14 re-measure):

  • spec_patterns — not a key. Discovery uses schema (optional; empty → auto-discover).
  • breaking_budget — not a key. The README example still writes it; the parser reads policy.max_breaking_changes. A top-level breaking_budget: 3 is ignored.
  • policy.no_delete — not a key. The parser has policy.no_delete_endpoints (boolean) and policy.no_delete_required_fields.
  • policy.freeze.start/end as a nested object — not a key. Freeze windows are freeze_periods[].
  • require_version_bump — the parser name is policy.require_version_bump_on_breaking.

Policy simulator

POST https://app.coderifts.com/api/v1/policy-simulator — API key required. Free $0; Team $149/month after beta (Team is $0 during public beta); Enterprise from $1,500/month. No Pro tier is sold. During the public beta every organization gets Team features at $0 with a self-serve key, public and private repositories alike, no separate Team key to request, and each key allows 1,000 requests a month: after that authorize returns BETA_LIMIT_REACHED, analysis keeps working, and one email to hello@coderifts.com raises the limit. The route is mounted behind the API-key middleware.

It runs the same parsePolicy / evaluateYamlPolicy pair against either a spec pair or a hand-built context. It does not write a check run. Use it to see which rule would fire before you put api-policy.yaml in a repo.