StagePatch documentation

StagePatch stages content changes and applies them as a reviewable patch, inside one site with the built-in Workspace or from a staging site to live. It never copies a database. This guide covers both setups.

Requirements

• WordPress 6.4 or newer, PHP 8.1 or newer with the zip and json extensions (present on virtually every host).
• Two-site mode: both sites on the same StagePatch version, and HTTPS on live for pushes.
• Single-site WordPress. Multisite is not supported.

Install

1. Download the free plugin from the StagePatch product page.
2. Plugins → Add New → Upload Plugin, choose the zip, install, activate. For two-site mode do this on both sites.
3. Open StagePatch → Settings and pick a mode: Workspace (one site), Recorder (staging) or Applier (live).

Quick start: Workspace on one site

1. Set the mode to Workspace. Nothing changes for visitors.
2. Edit pages and posts as usual. Opening a live item opens a staged copy; the list table shows “Has staged edits”. Publishing a new post keeps it staged, and Trash stages a deletion.
3. Preview the whole site as it will look from the admin bar: Workspace → Staged view.
4. When ready, open StagePatch → Workspace. It runs a dry run against the live content, shows conflicts field by field, and Apply to live writes everything with a rollback snapshot.
5. Changed your mind? Discard throws the staged copy away; the live item was never touched. Applied something wrong? Rollback restores the snapshot.

Editors can stage, preview, discard and mark items Ready for review. Applying, rolling back and dissolving batches need the stagepatch_apply capability, which administrators have by default. In the free plugin, menus, widgets, theme settings and options are edited live; StagePatch Pro stages those too.

Quick start: staging to live

1. Set the same shared secret (16 or more characters) under StagePatch → Settings on both sites, or define STAGEPATCH_SECRET in both wp-config.php files.
2. On live, set the mode to Applier.
3. Clone live to staging, then set staging to Recorder. This captures the baseline: objects that exist at this moment share IDs across the two sites; anything created later gets a UUID.
4. Work on staging. StagePatch → Changes lists every recorded edit with a before/after diff. Include or exclude changes and Create batch.
5. Export the batch as a signed zip (Export, or wp stagepatch export), upload it under StagePatch → Import on live, review the dry run and three-column conflict view, and apply. Every apply keeps a rollback snapshot.

What is recorded: pages and posts with their meta and terms, nav menus and items, terms and taxonomies, widgets, theme mods and the Customizer, allowlisted options, media attachments. Never recorded: users, orders, customers, sessions, cron, transients, comments and logs. WooCommerce product stock, price and sales meta are excluded even when products are opted in.

StagePatch Pro: activation, pushing and updates

1. Buy a plan on the StagePatch product page; the Lemon Squeezy receipt has your key and the Pro zip. Install stagepatch-pro.zip on both sites and activate it alongside the free plugin.
2. Enter the key under StagePatch → License on staging.
3. On live, create an Application Password for the user StagePatch should act as (Users → Profile → Application Passwords).
4. On staging, StagePatch → Push to live: enter the live URL, username and Application Password. Pushes are signed with the shared secret, protected against replay, and uploaded in chunks.
5. Push a batch. Live’s dry run appears inline; apply from the same screen, or from the command line with wp stagepatch push --apply.

Pro also extends the Workspace: settings screens, the Customizer, widgets and menu locations saved in the admin are held until applied, and classic menus can be staged as a copy from Appearance → Menus. Pushing and staging keep working whatever the license status; a valid key is needed for automatic updates, which arrive through Dashboard → Updates from hexcorp.io.

WP-CLI

wp stagepatch workspace [--apply]   # dry run, or apply, the workspace
wp stagepatch batches               # list batches
wp stagepatch export <batch>        # signed zip
wp stagepatch import <file>         # on live: validate + dry run
wp stagepatch apply <batch>         # apply with rollback snapshot
wp stagepatch rollback <batch>
wp stagepatch push [--apply]        # Pro

Troubleshooting

• “Below baseline” warning on Settings: staging was not cloned from this live site after the baseline was taken. Re-clone, then switch Recorder on again.
• A large push times out: raise max_execution_time on live, or export and import the bundle instead; chunked uploads resume where they stopped.
• nginx: uploaded bundles live under uploads/stagepatch with Apache and IIS protection files; on nginx add a location block that denies that path.

Getting help

Email hello@hexcorp.io with both site URLs, the StagePatch version and, for an apply problem, the batch’s dry-run report (StagePatch → Import → Download report). Reports never contain server paths or secrets.