Update runs

An update run applies updates to a throwaway copy of your site, checks the result, and waits for you. If you approve it, Ledge opens a pull request with the changes. Nothing reaches your live site until you merge that pull request and deploy it.

Before you startCopy Anchor Link

Every update run needs the site's repository linked. Ledge tests the linked branch as it is now.

• Craft CMS sites also need the plugin with LEDGE_ACQUIRE_ENABLED=true, because the run starts from a copy of the production database. See Install the Craft plugin.
• Laravel apps only need the linked repository. The run uses your test suite instead of a database copy.

Read Security before turning update runs on for a client's site. The sandbox receives production data.

Start a runCopy Anchor Link

Open the site's Updates page and click Test Update. If something's missing, the page shows the next step instead.

For Craft sites, the dialog lists the pending updates:

• Everything is updated to its latest version by default. Under Advanced — pick versions, untick packages to leave them alone, or choose a specific version.
• Run composer update too also updates the libraries Craft and its plugins depend on, such as Twig and Guzzle. It's on by default.
• Update packages with expired licenses includes plugins whose licence has run out. They're skipped otherwise.
• If the site has open advisories, the dialog shows which ones the run should fix, and which need a major upgrade or have no fix yet.

Click Authorize & Start. You can also start runs from an AI assistant with start-update-run, or across many sites at once with Campaigns.

Run configurationCopy Anchor Link

Configure on the Updates page sets how the sandbox is built:

• Environment overrides replace production values in the sandbox, such as a test API key in place of a live one. They're encrypted at rest.
• Build commands run after composer install, before the update. Leave them empty to use your package.json build script. Choose the Node version, or let Ledge read .nvmrc.
• Test settings (Laravel only): the test database (SQLite, MySQL or PostgreSQL), whether to start Redis, and the test command. Ledge detects Pest or PHPUnit.

What a run doesCopy Anchor Link

A run must finish within an hour, including the time it takes to copy the database.

StatusesCopy Anchor Link

Needs review means one of these:

• Craft: the crawl found a page error, Craft logged a new error, or production's project config is ahead of the repository. Pages that were already broken on production show up too, because Ledge only crawls after the update. Fixing broken pages in your sitemap gives cleaner results.
• Laravel: tests failed, the suite couldn't run, or no test suite was found.

The crawl never fails a run. It only sends it to review.

Preview the updateCopy Anchor Link

Craft runs that reach Ready to apply or Needs review have a preview: a working copy of the updated site. Open it from Preview the updated site on the run page. The username and password are on the same card, and the password is unique to the run.

Anyone with the link and password can open the preview, so share it only with people who could see the live database.

• The preview sleeps after 2 hours without visits. The first visit after that can take a minute.
• It's removed when you approve, reject or cancel the run, or 7 days after the run finished. You can still approve a run after its preview has gone.

Approve, reject or cancelCopy Anchor Link

• Approve & Open PR opens the pull request. Tick Auto-merge when checks pass to have Ledge merge it once your CI passes.
• Reject closes the run without a pull request. You can add a reason, which is kept in the site's history.
• Cancel stops a run in progress.

Each of these deletes the sandbox.

The pull requestCopy Anchor Link

Ledge pushes a new branch, named like ledge/craft-update-2026-11-09-a1b2c3, and opens a pull request against the linked branch. The pull request lists the packages that changed and the run's results.

It can only change composer.json, composer.lock and, on Craft sites, files in config/project/. Your branch protection rules and CI still apply.

From the run page you can Merge PR once the pull request can be merged, or arm auto-merge to merge when checks pass. Auto-merge is cancelled if checks fail or the pull request has conflicts. On a repository with no CI checks, auto-merge merges straight away.

After the merge, your usual deploy takes over. If the default branch runs GitHub Actions, the run page shows whether the deploy succeeded.

Scheduled update runsCopy Anchor Link

Click Automatic updates on the Updates page to test updates on a schedule.

• As needed checks every day at the chosen time and starts a run when updates are waiting.
• Cooldown holds back new releases until they're that many days old, so you skip releases that get pulled or patched within a day or two. Set it to 0 to always use the latest.
• Auto-merge when clean opens the pull request and merges it once checks pass, for runs that finish Ready to apply. Runs that need review always wait for you, and so do runs that move Craft or a plugin to a new major version.
• Respond to advisories starts a run as soon as a security advisory has a fix, skipping the schedule and cooldown.

A scheduled run doesn't start while another run on the site is waiting for you. Scheduled runs skip plugins with expired licences.

When a run failsCopy Anchor Link

When a run fails, Ledge reads the end of the log and explains what went wrong, with a suggested fix and the packages that blocked it. Common causes:

• Dependency conflict: two packages need versions of a library that can't both be met.
• PHP version: an update needs a newer PHP than the site runs. See Set the PHP version.
• Site error: composer install or migrations failed, often for the same reason they would on production.
• Temporary problem: a timeout or a network error. Try the run again.

The full log is on the run page under Log. Run history is kept for 180 days.

AlertsCopy Anchor Link

Update runs alert the site's notification policies when a run is ready for review, needs review, finishes with no changes, fails, or is merged. Runs started from a campaign don't send per-site alerts.