Repository configuration

Place diffraction.yml at the root of the repository being reviewed. Commands, routes, viewports, budgets, and review rules belong in this file. Credentials belong in secret stores; the file may contain secret reference names only.

Starting configuration

This example assumes a pnpm web application with build and start scripts. Adapt its commands, route, and checkpoint to your application before running it. The score scale and budget below are example choices for the repository owner.

diffraction.yml

version: 1
app:
  install: pnpm install --frozen-lockfile
  build: pnpm build
  start: pnpm start --port 3000
  port: 3000
  readyUrl: http://127.0.0.1:3000
  workingDirectory: .
review:
  mode: standard
  scoreScale: 5
  importantRoutes: [/]
  flows:
    - name: Open the homepage
      route: /
      objective: Verify the main entry point remains usable.
      checkpoints:
        - The primary navigation is visible and usable.
  browsers: [chromium, firefox]
  viewports:
    - name: desktop
      width: 1440
      height: 900
    - name: mobile
      width: 390
      height: 844
  budgets:
    maxDurationMs: 600000
    maxSteps: 20
    maxAiTokens: 30000
    maxCostUsd: 0.9
    maxRetries: 1
    maxMediaDurationMs: 180000

Review controls

Field	Purpose
`review.mode`	`budget`, `standard`, or `deep` review mode.
`review.scoreScale`	Owner-selected scale of `3` or `5`.
`review.flows`	Named objectives and checkpoints; an optional `persona` adds context.
`review.browsers`	A nonempty selection of `chromium`, `firefox`, and `webkit`.
`review.viewports`	Named dimensions; every selected browser/viewport pair needs its own recording.
`review.e2eCommand`	Optional command for existing end-to-end tests.
`review.triggers`	`alwaysRun` and `ignore` patterns used by UI-impact detection.
`review.brand`	`rules`, `rulePaths`, and `referenceImages` supplied by the repository.

The current schema requires a positive maxCostUsd strictly below 1. Higher budgets are not supported by this schema. Runtime limits and available provider configuration can constrain a run further.

Network and secrets

app.network optionally requests installationAllowedHosts, runtimeAllowedHosts, and browserAllowedHosts. Entries are public DNS hostnames, with optional leading wildcards; URLs and IP addresses are rejected. Production egress authorization uses the immutable base revision, so a pull request cannot grant itself new network access through its own configuration. secrets.references accepts uppercase secret names. Declaring a reference does not provision a credential or authorize exposing production secrets to PR code. The configuration parser is the authoritative field contract and rejects unknown properties.

Get started

Run a review

Reference

Repository configuration

Starting configuration

Review controls

Network and secrets

​Starting configuration

​Review controls

​Network and secrets

Starting configuration

Review controls

Network and secrets