Quickstart

Start with a repository you own, a dependency upgrade already understood by your team, and a required CI check that exercises the affected integration. PatchFlow opens a draft pull request and never merges it.

Choose the first repository

• Choose a non-critical repository with a reproducible lockfile and test command.
• Install the PatchFlow GitHub App on only that repository (hosted pilot) or use a short-lived GitHub token for local CLI evaluation.
• For CLI runs, connect the same repository to Cursor separately. The hosted pilot launches agents with PatchFlow-managed provider credentials.
• Name at least one required GitHub Check that covers the dependency integration.

Configure a controlled upgrade

{
  "repos": [{
    "url": "https://github.com/acme/checkout",
    "startingRef": "main",
    "packages": ["stripe"],
    "setupCommand": "auto",
    "testCommand": "npm test",
    "testGate": "checks",
    "requiredChecks": ["test"],
    "testEnvPassthrough": []
  }],
  "policies": {
    "allowedUpdateTypes": ["patch", "minor", "major"]
  }
}

Run a specific version transition

npm run patchflow -- run \
  --package stripe \
  --from 16.0.0 \
  --to 17.0.0 \
  --repo https://github.com/acme/checkout

What you should see

• Evidence level playbook and update type major in the run log
• A draft pull request upgrading the package and its call sites
• GitHub Checks polled on an immutable PR head SHA
• A stale verdict discarded automatically if the branch moves during verification
• patchflow:ready when the gate passes
• patchflow:needs-attention plus test output when it fails

Run without a config file

npm run patchflow -- run -p stripe --from 16.0.0 --to 17.0.0 \
  --repo https://github.com/acme/checkout \
  --setup-command "npm ci" \
  --test-command "npm test"