Documentation — Patchwork

Install

Patchwork is a GitHub App. Installing it is the entire setup.

Open the installation page and choose an account or organisation.
Pick selected repositories rather than all of them. Patchwork only ever looks at what you choose, and you can change the selection later.
That's it. The first sweep runs within the hour, then daily.

Patchwork asks for three permissions: Contents (read and write) to clone and push a branch, Pull requests (read and write) to open the PR and check whether one is already open, and Metadata (read) to list which repositories the installation covers. It requests nothing else — no secrets, no Actions, no organisation members.

How a run works

Every run is the same six stages. You can watch them execute in real time on the demo.

Stage	What happens
`detect`	Compares the dependencies in your manifest against the live npm or PyPI registry. A watched package a major behind is a breaking change you're exposed to.
`ingest`	Reads the migration guide or changelog for that version jump.
`extract`	Turns that prose into a structured list of breaking changes — removed symbols, renamed methods, changed response shapes.
`locate`	Clones the repo, narrows to candidate files with a fast text scan, then confirms each one against the abstract syntax tree. Text matches that aren't real usages are discarded here.
`migrate`	Rewrites only the regions containing confirmed usages, and bumps the dependency in your manifest so the new code compiles against the new major.
`verify`	Runs your own build in a clean checkout. See below — this is the important one.

One major at a time

When a package is several majors behind, Patchwork walks it up one major per pull request rather than attempting a single leap, and each rung is verified before the next is attempted. Each pull request opens against the previous one, so the diff you review is that hop alone.

This is about correctness, not just review size. Comparing the installed major directly against the latest is blind to anything introduced and then removed in between: for openai, the 98 symbols dropped in v5 were added in v4, so a v3-to-v7 comparison never sees them at all. Walking the ladder does.

A hop that removes nothing your code could use carries its version bump forward instead of opening an empty pull request, and a hop that fails to verify stops the chain there — later hops would be building on code we could not prove compiles.

The AST step is what separates this from find-and-replace. A .data accessor on an axios response is not a .data accessor on an OpenAI response, and only one of them should change. Across the benchmark suite this produced zero false-positive file edits.

What green means

Patchwork runs your project's own build before opening anything, resolved in this order:

npm run build, if you have a build script
tsc --noEmit, if there's a tsconfig and TypeScript is installed
npm run typecheck
npm test

The baseline guard. If the build fails, Patchwork reverts its edits and builds again. If your project didn't compile before the migration either, the failure isn't attributed to the rewrite — you get a draft that says the baseline was already broken, instead of a PR blaming Patchwork for a break that was already there.

Installation runs with dependency lifecycle scripts disabled, under a memory cap and a wall-clock timeout that kills the process group on breach. Your build script cannot read Patchwork's credentials — the environment is stripped before it runs.

Green means it compiled. It does not mean behaviour is unchanged. Review the diff like you would a colleague's.

The pull requests

Every change lands on its own patchwork/* branch. Nothing is ever committed to your default branch.
A PR that verified opens ready for review. One that didn't opens as a draft titled [needs review], with the build errors in the body.
Patchwork will not open a second PR for a package while one is still open on that repository.
Patchwork never merges. That stays yours.

Languages

TypeScript and JavaScript against npm, and Python against PyPI. The pipeline itself is language-agnostic — each language is an adapter that knows how to parse, locate usages, install, and build.

Configuration

There is nothing to configure for the default behaviour. If you need to pin how verification runs, these are read from the environment where the worker runs:

Variable	Effect
`PATCHWORK_VERIFY_COMMAND`	Pin the verify command instead of auto-detecting it.
`PATCHWORK_VERIFY_TIMEOUT_MS`	Wall-clock budget for install plus build. Default 300000.
`PATCHWORK_SCHEDULE_MS`	How often the sweep runs. Default 24 hours.
`PATCHWORK_ALLOW_DUPLICATE`	Set to 1 to allow a second open PR per package. Default is idempotent.

Self-hosting

The worker is a container. It needs git, npm and a writable filesystem, which is why it can't run on serverless platforms.

docker build -t patchwork-worker .
docker run -p 8080:8080 --env-file .env patchwork-worker

Point your own GitHub App's webhook at /webhook on that host, set GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY_BASE64, GITHUB_WEBHOOK_SECRET and OPENAI_API_KEY, and the scheduler runs continuously. GET /health reports whether credentials loaded.

Troubleshooting

Patchwork opened a draft instead of a normal PR

Verification failed. Check the PR body: if it says the baseline was already broken, your project didn't compile before the change either. Otherwise the build errors are listed and the rewrite needs a hand.

Nothing has happened since I installed it

Most likely nothing is out of date. Patchwork only acts when a watched dependency is a major behind — if everything is current, it stays quiet by design. Check status to confirm the worker is up.

It changed a file I didn't expect

Close the PR and tell us at pandey.abhisaar222@gmail.com. A false-positive edit is a bug in the locate stage and we want the repro.

I want it off

Uninstall the GitHub App. Access is revoked immediately and no copy of your code is retained — see the privacy policy.

Everything Patchwork does, and why it stops where it does.