Concepts

Test gates

Use required GitHub Checks as the production trust boundary, with local execution only for evaluation.

Mode	Behavior	Best for
checks	Wait only for GitHub Checks	Production repositories
local	Clone, set up, and test on the machine running the CLI	Local CLI evaluation only
auto	Prefer checks; use local only if none appear	Early evaluation

Required checks

When requiredChecks is non-empty, every named check must appear and finish with success. Missing, skipped, neutral, cancelled, or failed required checks do not pass.

Leaving requiredChecks empty is weaker: any completed check can satisfy the gate, so a fast lint or preview-deploy job could pass a PR whose test workflow had not registered yet. PatchFlow warns when it runs unpinned and waits for the observed check set to stay unchanged for checkStabilizationSeconds (default 60) before trusting it. Name your checks in production.

patchflow.config.json

{
  "testGate": "checks",
  "requiredChecks": ["lint", "unit", "integration"]
}

Diff policy

Before any test gate runs, PatchFlow checks that the agent's diff is actually a dependency upgrade: within the file-count limit, clear of forbidden paths, and leaving a manifest range that admits the target version. CI definitions are forbidden by default, because an agent that can edit its own test gate can pass it.

A diff-policy failure short-circuits the test gate. The check runs produced by a modified workflow are exactly the evidence PatchFlow must not trust, so it labels the PR patchflow:needs-attention without reading them.

patchflow.config.json

{
  "policies": {
    "diffPolicy": {
      "maxChangedFiles": 50,
      "forbiddenPaths": [".github/workflows/", ".github/actions/"],
      "requireManifestBump": true
    }
  }
}

Local setup

Auto setup selects npm ci, pnpm, Yarn, Bun, or npm install from the repository lockfile. A setup failure ends the gate before tests run. Set setupCommand to none only for a self-contained test command.

patchflow.config.json

{
  "setupCommand": "auto",
  "testCommand": "npm test",
  "testGate": "local"
}

Commit-bound verdicts

PatchFlow evaluates diff policy and checks against one immutable PR head SHA. If the branch moves while verification is running or while the ready label is being applied, the stale result is discarded and the label is removed.

Branch protection and required human approval remain the merge authority. The PR comment records the exact verified commit for auditability.

Retries

A failed gate may resume the same agent with a bounded test-output excerpt. maxRetries is capped at three. Every attempt re-reads the PR head SHA before gating again; infrastructure failures never instruct the agent to modify code.

NextProduction operation