Configuration as code

A .warpway.yml file versions your review policy with your code: which lenses are required, extra rules, who answers which questions, what blocks a merge, runtime verification profiles and auto-approval conditions. Configuration as code is part of the Team plan. Everything in the file can also be set in the dashboard, and the dashboard can turn your settings into a proposed .warpway.yml change for you to merge.

Where the file lives

Warpway reads the first of these files that exists:

1. .warpway.yml
2. .warpway.yaml
3. .github/warpway.yml
4. .github/warpway.yaml

The base-branch rule

If a pull request edits .warpway.yml, that edit does not apply to its own review; Warpway notes in the summary that the pull request changes Warpway configuration. For example, a pull request that removes security from required_lenses is still reviewed with Security required. The change takes effect for pull requests opened against the branch after it merges.

How settings combine

Warpway resolves one effective policy per repository and base commit, in this order, later layers overriding earlier ones:

1. Warpway's defaults: the built-in lenses, plus your organization's custom lenses;
2. organization settings;
3. organization lens settings (which lenses are on and required, edits to built-in and custom lenses, and lens locks);
4. repository settings in the dashboard;
5. repository lens settings;
6. .warpway.yml on the base branch.

Sections such as merge_gate merge field by field, and a list inside a section replaces the list from the layer below. required_lenses, disabled_lenses and conditional_lenses add to the layers below, and a rule replaces a lower layer's rule with the same id. In repository lens settings and in .warpway.yml, a lens's instructions, required_evidence and runtime_profiles add to what it already has and its tools can only be narrowed, so a repository can extend a lens's guidance but never strip it.

Then three limits apply:

• Organization locks. Settings an Owner locked at the organization level cannot be changed by repository settings or by the file. A locked key in the file is ignored, and Warpway lists the ignored keys with the review.
• Plan limits. Features your plan does not include are switched off, and the trust level is capped at your plan's maximum. On the Free plan .warpway.yml is not applied at all.
• Trust capping. trust_level in the file can lower the repository's trust level, never raise it.

The result is stored as a policy version identified by its hash, and every review records which version it used.

Validation

Warpway validates the file against the schema below and reports each problem in plain language with its line and column, for example 'severe' is not a valid severity for `merge_gate.block_on_severities[1]`. Use one of: critical, high, medium, low, info. Unknown keys are errors, which catches typos: merge_gates: is reported as Unknown setting 'merge_gates'. Did you mean 'merge_gate'?

If the base branch's file is invalid, Warpway does not guess what you meant and applies none of it. The review runs with your organization and repository settings, every error becomes a configuration blocker, and the review policy cannot be satisfied until the file is fixed. At Gate and above the check fails.

A complete example

version: 1

required_lenses:
  - correctness
  - security
  - testing

rules:
  - id: tenant-isolation
    lens: security
    applies_to:
      paths:
        - src/data/**
        - src/api/**
    instructions: >
      Every access path to tenant-owned records must establish tenant
      ownership before returning or mutating data.

routing:
  security:
    github_team: "@company/security"
    slack_group: "security-team"

merge_gate:
  require_all_required_lenses_resolved: true
  require_zero_open_human_tasks: true

auto_approve:
  enabled: false

The smallest valid file is version: 1; every other key is optional.

Reference

version

Required. Must be 1.

trust_level

An integer from 0 to 4 that lowers the repository's trust level for reviews under this file. It can never raise the level set in the dashboard or allowed by your plan. See Trust levels.

required_lenses

Lens keys that are required: whenever a required lens applies to a pull request, it must run and be resolved before the policy is satisfied. Listing a disabled lens here also turns it on.

version: 1
required_lenses:
  - correctness
  - security
  - testing
  - database_safety

Requiring a lens does not change when it applies. Correctness, Security and Testing apply to every pull request; a lens with narrower applicability, such as database_safety, is required on the pull requests it applies to and does not run on the others. To require a lens on every pull request, also set its applies_when to always: true under lenses. required_lenses only adds requirements; to make a lens optional, set required: false under lenses.

disabled_lenses

Lens keys that do not run in this repository. A lens required by a locked organization setting cannot be disabled here.

conditional_lenses

Lenses that run, and become required, only when the change matches a condition, even if the lens would not otherwise apply.

version: 1
conditional_lenses:
  - lens: database_safety
    when:
      paths:
        - db/migrations/**
      languages:
        - sql
    required: true
  - lens: product_semantics
    when:
      categories:
        - billing
        - payments
    required: true

lenses

Custom lenses and changes to existing lenses, keyed by lens key. The key of a built-in lens, or of one of your organization's custom lenses, changes that lens; any other key defines a new custom lens, which needs name and instructions, or extends.

version: 1
lenses:
  performance:
    blocking: block
    applies_when:
      paths:
        - services/api/**
  hipaa_phi:
    name: HIPAA PHI Handling
    applies_when:
      paths:
        - src/patient/**
    instructions:
      - Confirm PHI is not written to application logs.
      - Confirm access remains tenant-scoped.
    human_signoff: always
    ai_clear: false

rules

Extra instructions attached to an existing lens, optionally for specific paths. Up to 200 rules.

routing

Who answers questions, keyed by lens key, or default for all lenses without their own entry. Each entry is a routing target:

See Routing for how these combine with CODEOWNERS and history.

reviewer_requests

merge_gate

What must be true for the review policy to be satisfied. Enforced as a blocking check at trust level 2 (Gate) and above.

version: 1
merge_gate:
  require_all_required_lenses_resolved: true
  require_zero_open_human_tasks: true
  block_on_severities:
    - critical
    - high
  required_ci_checks:
    - build
    - unit-tests
  fail_on_incomplete: true

runtime

Approved runtime verification profiles under profiles, keyed by profile name (letters, digits, _ or -, up to 40 characters, starting with a letter or digit), up to 25 profiles. Warpway can dispatch only the profiles listed here, and only once runtime verification is enabled for the repository in the dashboard.

version: 1
runtime:
  profiles:
    unit:
      workflow: warpway-verify.yml
      input: unit
      timeout_minutes: 20
      required_for_lenses:
        - testing
    integration:
      workflow: warpway-verify.yml
      input: integration
      timeout_minutes: 30
      run_when:
        paths:
          - services/**

See Runtime verification for the workflow template.

auto_approve

Conditions for automatic approval. Auto-approval also requires the Team plan, trust level 4, and an Owner's explicit enablement in the dashboard; this section alone never turns it on. See Auto-approval.

version: 1
auto_approve:
  enabled: true
  docs_tests_only: true
  max_changed_lines: 200
  max_files: 10
  excluded_paths:
    - auth/**
    - migrations/**
  excluded_categories:
    - auth
    - authorization
    - migration
  required_ci_checks:
    - unit-tests

review

Which pull requests and files Warpway reviews.

version: 1
review:
  include_drafts: false
  ignore_paths:
    - "**/*.snap"
    - "**/generated/**"
    - pnpm-lock.yaml
  ignore_authors:
    - renovate[bot]
  base_branches:
    - main
    - release

knowledge

slack

Applicability

applies_when (lenses), applies_to (rules), when (conditional lenses) and run_when (runtime profiles) share one shape. A condition matches when any of its parts matches:

A condition with only exclude_paths matches every pull request that changes something outside those paths.

Globs match repository-relative paths with / separators: * matches within one directory, ** across directories, and files starting with . are matched like any other. Matching is case-sensitive. Each list holds up to 200 patterns of up to 300 characters.

Semantic categories

The change analysis tags each pull request with the categories that describe it. Use them in applicability conditions and in auto_approve.excluded_categories:

auth, authorization, billing, payments, pii, data_model, migration, api_contract, public_sdk, events, ui, infra, ci, dependencies, config, docs, tests, concurrency, caching, performance_sensitive, security_sensitive, feature_flag, business_logic, logging, external_integration.

Lens keys

Built-in lenses: correctness, security, testing, architecture, compatibility, performance, product_semantics, database_safety. Custom lens keys use lowercase letters, digits, _ or -, 2–63 characters, starting with a letter or digit.

Severities

From most to least severe: critical, high, medium, low, info. By default critical, high and medium findings block the merge gate; change that with merge_gate.block_on_severities.

Organization locks

An Owner can lock any of these top-level keys for the whole organization: trust_level, required_lenses, disabled_lenses, conditional_lenses, lenses, rules, routing, reviewer_requests, merge_gate, runtime, auto_approve, review, knowledge, slack. A single lens can be locked too. A locked key keeps the organization's value in every repository: neither repository settings nor .warpway.yml can override it, and an attempt is ignored and reported with the review.

Locks apply to what a change does, not only to how it is spelled. With required_lenses locked, a repository can neither make a lens the organization requires optional, disable it, nor change when it applies; with routing locked, a lens's own routing block is ignored as well.

Proposing changes from the dashboard

Changes made in the dashboard are saved as repository settings and apply from the next review. .warpway.yml on the base branch still overrides them wherever both set the same key. To keep policy in version control instead, generate the equivalent .warpway.yml change from the dashboard and merge it through a pull request like any other change. Because the file is read from the base branch, it takes effect once merged.