Reference

Configuration reference

Every repository, timing, model, gate, and operational-policy setting.

Complete example

patchflow.config.json

{
  "repos": [{
    "url": "https://github.com/acme/checkout",
    "startingRef": "main",
    "packages": ["stripe"],
    "setupCommand": "auto",
    "testCommand": "npm test",
    "testGate": "checks",
    "requiredChecks": ["lint", "test"],
    "testEnvPassthrough": []
  }],
  "pollIntervalMinutes": 60,
  "model": "composer-2.5",
  "checkTimeoutMinutes": 15,
  "checkPollIntervalSeconds": 20,
  "checkStabilizationSeconds": 60,
  "policies": {
    "allowedUpdateTypes": ["patch", "minor", "major"],
    "packageAllowlist": [],
    "packageDenylist": [],
    "maxConcurrentMigrations": 1,
    "maxRunsPerCycle": 10,
    "cooldownMinutes": 60,
    "draftPullRequests": true,
    "maxRetries": 1,
    "maxAttemptsPerVersion": 2,
    "diffPolicy": {
      "maxChangedFiles": 50,
      "forbiddenPaths": [".github/workflows/", ".github/actions/"],
      "requireManifestBump": true
    }
  }
}

Repository fields

Field	Default	Notes
startingRef	main	Agent base branch
setupCommand	auto	auto, none, or a shell command
testCommand	npm test	Runs only after setup succeeds
testGate	auto	auto, checks, or local
requiredChecks	[]	Exact GitHub Check names
testEnvPassthrough	[]	Extra environment variable names the test command may see

Timing

Field	Range/default
pollIntervalMinutes	above 0; default 60
checkTimeoutMinutes	above 0; default 15
checkPollIntervalSeconds	above 0; default 20
checkStabilizationSeconds	0 or greater; default 60

Policy limits

Field	Range/default
maxConcurrentMigrations	1–10; default 1
maxRunsPerCycle	1–100; default 10
cooldownMinutes	0 or greater; default 60
maxRetries	0–3; default 1
maxAttemptsPerVersion	1–20; default 2
draftPullRequests	default true

Diff policy

Field	Range/default
diffPolicy.maxChangedFiles	1 or more; default 50
diffPolicy.forbiddenPaths	default [".github/workflows/", ".github/actions/"]
diffPolicy.requireManifestBump	default true

NextRun states and labels