module SiteSync – Frontend Developers Friend

[Mikel]

Hey everyone!

Our frontend developer saw GitSync and said "this is lovely for module repos — but what I actually want is the whole /site/ on a branch. Push, switch, done." Reasonable. We said "yeah, we'll get to that." That was a while ago. SiteSync is what we eventually built.

What it does: SiteSync deploys a ProcessWire installation's /site/ from a configured GitHub repository — one repo active at a time, but repoint it whenever you like, we're not the boss of you. Every template, stylesheet, RockMigrations config file, content seed lives on a branch. The admin lists every branch in the repo, you click Switch, /site/ is atomically replaced with that branch's tree, RockMigrations applies schema changes on the refresh hook, content seeds run. Click another branch, switch back. Click Rollback on yesterday's deploy, you're on yesterday's deploy. No git binary on the server, no CI runner, no SSH keys — everything goes over the GitHub REST API from PHP.

What's new here:

• Coding-agent fluent. An AI coding agent (Claude Code, Cursor, OpenAI Codex, …) reads a shipped AGENTS.mdfrom your ProcessWire root — which SiteSync auto-scaffolds on install — edits files on a feature branch, opens a draft PR, and the SiteSync admin shows you updates available. We bootstrapped a complete blog — schema, templates, styling, three seed articles — from an iPhone with the Claude app. No laptop in the loop.
• Real staging via two installs. One SiteSync per environment, both pointed at the same repo, different active branches. Feature → PR onto staging → staging auto-deploys → browse staging.example.com like an actual human → second PR onto live-stable → live deploys. Schema changes hit the staging DB first, not directly into live. The grown-up workflow you usually pay a SaaS for.

Quote

SiteSync is a small module with a tight scope. It doesn't try to be a deploy framework. It tries to be a deploy mechanism that composes cleanly with what's already in your PW toolbox — RockMigrations on top, hand-installed modules untouched on the side. From the agent side, that turned out to be exactly the right shape. If you've been doing manual export/import dances between dev and live, give it a spin.

— A coding agent

The technical guts:

• Versioned everything. Each deploy is <branch> + <SHA> + <commit title> in the Recent deploys table. One-click Rollback to any prior row — the rollback is itself just a regular deploy of that exact tree, same atomic two-pass write, same snapshot, same tracked-sync.
• Tracked sync, not strict mirror. A new file in your branch shows up on the server. A file your branch never knew about (a third-party module's helper, a hand-edited template, last night's debug log) stays where it is. SiteSync only deletes what SiteSync itself wrote — verified by per-file blob SHA in managed-files.json.
• Atomic two-pass write. Pass 1 downloads every blob to <final>.sitesync-tmp next to its target. Any failure cleans up all tmp files; /site/ is never half-mutated. Pass 2 POSIX-renames each tmp → final.
• Pre-deploy snapshots as tar.gz, configurable retention, one-click restore. Your /site/ before SiteSync touches it. If you've ever pasted find . -delete into the wrong shell, this is your safety net.
• Webhook with hold-back. A direct edit on the server (3am emergency typo fix) is detected; the next webhook push to that same path is held back with HTTP 409 + a clear admin banner instead of silently overwriting your hotfix. The push waits patiently for you to commit and push the local change.

Fits your stack:

• RockMigrations marriage. Fields, templates, roles, permissions as config files under site/RockMigrations/. SiteSync deploys the files and calls $modules->refresh() — RockMigrations hooks the refresh and applies your schema changes. No custom post-deploy step, no extra wiring. Schema-as-code that actually deploys.
• Editorial seeds under site/content/ for the "first article" / "bootstrap pages" problem — every .php file in there runs on every deploy. The bundled AGENTS.md documents the conventions for keeping seeds safe: idempotency guards (so a re-deploy doesn't duplicate content), and versioned filenames like 99-patch-rename-foo-v1.php for the rare "we need to rename this on every install" case. Conventions, not magic — your seeds are plain PHP doing whatever you want.

What it doesn't try to do: replace your CI, sync site/assets/ (uploads stay where the editor uploaded them), or pretend to be a fleet deployer. One site, one active repo, one Switch at a time. The simplicity is the point.

Beta status: in active use on real ProcessWire sites. The atomic-deploy + tracked-sync + hold-back + snapshot machinery is stable. The agent-templates and staging walkthrough landed in the most recent sprint and would benefit from more real-world miles. Bugs, edge cases, and "wait, that's a weird hosting setup" reports very welcome.

Boring details:

• License: MIT.
• Requires: ProcessWire 3.0+, PHP 8.0+ with curl and phar extensions.
• GitHub token: fine-grained PAT, Contents: read only — read-only. SiteSync literally cannot modify your repo. If the server is ever compromised, the token can pull source code but not push anything back.

Get it:

• Repository: https://github.com/frameless-at/SiteSync
• Install: drop into /site/modules/SiteSync/, Modules → Refresh → Install
• README has the whole tour: config, webhooks, path filters, staging walkthrough, agent workflow.

Companion to (but not dependent on) GitSync — install both side by side if you want module-level granularity and whole-/site/ branch deploys. SiteSync can even reuse GitSync's GitHub token, because typing the same PAT twice is a crime.

One last flex: For a proof of concept we just used SiteSync in combination with Claude to migrate a 20-year-old blog — articles, comments, gallery images, the lot — out of its previous CMS into a fresh ProcessWire install. We just installed the module, pushed /site/ to a Repo and connected the agent to it. We fed it with a JSON Dump of the Blog-Data and said what we wanted: Schema as files on a branch, content as idempotent seeds, snapshots between attempts because of course the image migration didn't work on the first run (or the second, or the third). New /site/ deployed clean, two decades of writing intact, old URLs preserved. Tataaaa.

Curious to hear how it lands in your setup.
Cheer, Mike