compatcompatSign in

Inside a compat job

Exactly what happens between a breaking release and your pull request.

Seven phases, always in this order. Then the five rules that make it safe to run on code you own.

The full job, phase by phase

For readers who want the mechanics: seven phases, always in this order.

  1. 01Connect

    Install the compat GitHub App and pick the repositories it may see; nothing else is visible.

    Install compat-devGitHub App

    Only select repositories

    • your-org/compat-playground
    • your-org/billing-service
    • your-org/marketing-site
    • your-org/infra
    2 repositories. Nothing else is visible.Install

  2. 02Get a proposal, or ask

    compat checks every detected SDK daily, reads the release notes and proposes the migration with the instruction written; or you describe one yourself.

    New migrationcompat-playground
    Stripe
    Upgrade stripe from v14 to v18
    https://docs.stripe.com/upgrades
    Run migration

  3. 03Baseline

    compat clones the repository into a disposable sandbox and runs your own install, typecheck, test and build to learn what green looks like.

    Baseline on mainsandbox 1 of 1
    Sandbox started, repository cloned
    installpassed 3.0 s
    lintnot run, no script
    typecheckpassed 6.0 s
    testpassed 1.1 s
    buildnot run, no script

    compat learns what green looks like before it touches a file. Anything already failing here is labelled pre-existing later.

  4. 04Plan

    Claude reads the code and the upstream changes and writes a plan with explicit steps, the files involved and a confidence estimate.

    Planconfidence high

    Upgrade the Stripe SDK from v14 to v18, pin apiVersion to 2025-08-27.basil, and update the invoice webhook to read subscription from the new parent field.

    Affected files

    • package.json
    • src/billing.ts

    5 steps

    1. 1Bump stripe to ^18
    2. 2Regenerate the lockfile with npm
    3. 3Pin apiVersion
    4. 4Update handleWebhook for invoice.parent
    5. 5Run typecheck and tests

  5. 05Edit

    Changes go through a restricted tool set with no shell and no secrets, and lockfiles are regenerated by your package manager.

    Editrestricted tool set
    • read_file src/billing.tsallowed
    • write_file src/billing.tsallowed
    • write_file package.jsonallowed
    • run_script installallowed
    • shell not availabledenied
    • write_file .github/workflows/ci.ymldenied
    • read_env not availabledenied

    No shell, no secrets, no hand edits to CI or lockfiles. Repository content is treated as untrusted input.

  6. 06Verify and repair

    Your checks run again, new failures are repaired within a bounded budget, and failures that were already there are reported.

    Verify and repair0 of 3 repairs used
    installpassed 3.0 s
    typecheckpassed 6.0 s
    testpassed 1.1 s
    repair budget

    New failures are repaired within a bounded budget. This run needed none. Failures that were already on main are reported as pre-existing, not fixed silently.

  7. 07Pull request

    A branch is pushed, a pull request opens with the recorded evidence in its body, and a person merges.

    Pull request#2 open

    chore(stripe): migrate integration to 18.0.0

    integration-maintenance/stripe/8f2c into main

    Checks3 passed, 2 not run
    Files changed2
    Manual steps2 listed
    Mergea person, always
    Rendered from recorded evidence.Review

Built to be trusted with your code

Five rules, short enough to draw. The long version is on the security page.

  1. 01 of 04

    A disposable sandbox per job

    Your repository is cloned into a fresh sandbox that runs your checks, hosts the edits and is destroyed when the job ends; compat keeps no copy of your source.

  2. 02 of 04

    Evidence, not claims

    The pull request body lists every check as passed, failed or not run, with its duration, and a check that did not run is never presented as a pass.

  3. 03 of 04

    Tokens minted per job, never stored

    Each job mints a one-hour token scoped to that repository, uses it for the clone, the push and the pull request, and never writes it anywhere.

  4. 04 of 04

    Repairs inside a budget

    When your checks fail after an edit, compat repairs within a bounded loop, then stops and reports instead of guessing.

  • No production secrets by default

    Jobs run with your code and your package manager, not your environment. Checks that need real credentials are reported as not run.

  • Human merge only

    compat opens pull requests and has no merge capability. The branch it pushes is namespaced, and it never touches your default branch.

Ready to see it on your repository?

Try compat freeSee a real pull request