Guides

Production operation

Bound unattended work with policies, budgets, cooldowns, and required checks.

Start conservative

patchflow.config.json

{
  "policies": {
    "allowedUpdateTypes": ["patch", "minor"],
    "packageAllowlist": ["stripe", "@aws-sdk/client-s3"],
    "packageDenylist": [],
    "maxConcurrentMigrations": 1,
    "maxRunsPerCycle": 5,
    "cooldownMinutes": 60,
    "draftPullRequests": true,
    "maxRetries": 1,
    "maxAttemptsPerVersion": 2
  }
}

Run one poll cycle

Use one-cycle mode in a scheduler first. It is easier to observe and gives the scheduler ownership of restarts.

Terminal

npm run patchflow -- watch --once

Then run continuously

Set requiredChecks for every production repository.
Keep draftPullRequests enabled.
Use maxRunsPerCycle as the hard agent-run budget per cycle, and maxAttemptsPerVersion as the budget per upgrade.
Increase concurrency only after CI and rate limits are understood.
Review inferred and major migrations more carefully.

Terminal

npm run patchflow -- watch

Budgets stop runaway spend

A migration that can never pass would otherwise be rediscovered as new work on every poll, starting a fresh cloud agent each time. maxAttemptsPerVersion (default 2) abandons a (package, version, repository) triple once it is exhausted, and records the version as seen so the next cycle moves on. cooldownMinutes (default 60) spaces out consecutive attempts against the same repository.

Important

State writes are serialized by an in-process mutex and an advisory lock file, so a second watch process fails fast rather than silently overwriting the first. This is advisory, not a distributed lease: it does not coordinate across machines or shared filesystems.

NextPrivate repositories