How WordPress sync works

Workover does not host your content and does not sit in front of your site. It talks to WordPress through the REST API, using credentials you gave it, and it does so only when you ask. Understanding the model takes two minutes and saves a lot of confusion later.

Two copies, one link

When a document is linked to a WordPress post, there are two copies of that content: the one in Workover and the one in WordPress. Neither is automatically authoritative. They are reconciled by three deliberate actions:

• Push — send the Workover version to WordPress, overwriting the post.
• Pull — fetch the WordPress version into Workover, overwriting the document.
• Sync from WordPress — bring a whole project into line with the site at once: import posts Workover has not seen yet, and refresh the details of the documents it already has. Described in full below.

No document body you have written in is ever merged or silently replaced by any of them, and that is on purpose. Content is not a database row; an automatic merge of two edited drafts produces something nobody wrote. Workover instead tells you which side is ahead and makes you choose.

Push and pull are per document and always yours to trigger. A sync is per project, and is the one action Workover also performs on its own.

What Workover remembers

At the moment of a push or pull, Workover records when the WordPress post was last modified. That single timestamp is what everything else is built on. It also records each post’s live URL and whether it is published, which is how Workover knows where a link to that document should point.

Periodically, and when you open a project, Workover re-checks the modification time of the linked posts. If a post changed since the timestamp it recorded, it knows WordPress has moved on. That is what produces the WordPress is newer badge, and it is why a push can be refused — see sync status and conflicts.

What a push actually sends

A push is a single write to the WordPress REST API containing:

• The body, converted from the editor’s format into Gutenberg block markup.
• The title.
• Any fields you changed in the WordPress panel — status, slug, excerpt, categories, tags, featured image, author, publication date, SEO fields, custom fields.

Fields you did not touch are not sent at all. This matters: a push never blanks something you left alone, so a setting configured in WordPress and never mirrored in Workover survives.

Images

Images in a document are stored by Workover. Before a push, any that WordPress does not already have are uploaded into your media library and the body is rewritten to point at them there. The published page therefore does not depend on Workover being reachable, and disconnecting later does not break your images.

Links to other documents

A link to another Workover document only works for people signed in to your workspace. So before a push, each one is rewritten to the linked article’s live URL on your site. The Workover address stays in your document and the URL is worked out again on every push, so a link to an article that wasn’t live yet starts working the next time you push after it goes live. A link to a document that isn’t live is removed and its text kept, and Workover asks you first. Linking to other documents in a WordPress post covers the details.

Content WordPress has that the editor cannot represent

Some things do not survive a round trip through a rich-text editor — ACF fields, shortcodes, and custom or third-party blocks. Workover preserves these rather than converting them: they are carried through untouched and written back as they were.

When a post is mostly made of those, Workover will say so and offer to edit it as blocks instead, which avoids the conversion entirely. Custom blocks and ACF fields explains when that happens.

What a pull does

A pull replaces the document body with what is on WordPress, converting block markup back into editor content, and re-records the timestamp. Your Workover edits to that document are replaced — which is why Workover warns before a pull that would discard unpushed work.

Previous versions are kept, so a pull is recoverable: version history will still have what you had before it.

Syncing a whole project

Push and pull act on one document. Sync from WordPress, in the project’s toolbar, acts on the whole site at once.

Press it after connecting a site, or whenever posts have been written in WordPress that Workover has not seen. It walks every public post type on the site and does two things: it creates a document for each post the project does not have yet, and it refreshes the details of the documents it already has.

Imported posts are not limited to published ones — drafts, scheduled, pending and private posts all come across, as documents in the matching workflow status. If the connected WordPress account is not allowed to read unpublished posts, Workover imports what it can and names the post types it could only read published posts from, rather than reporting a clean sync it did not achieve.

It is safe to press repeatedly. A post that already has a document is matched to it rather than imported a second time, so a sync that finds nothing new simply reports that the project is already up to date. On a large site the work moves to the background and the new documents appear in the list as they arrive.

Workover also runs this same refresh on its own, when it notices the site has posts it has no document for. So the behaviour below is not confined to the moment you press the button.

What a sync protects

A document you have opened in Workover keeps its body. Edits you have not pushed are not overwritten, and neither are WordPress field edits you have staged but not yet pushed — a slug, an excerpt, categories, tags or SEO fields all survive a sync untouched.

Only a document that has never been opened here has its body replaced, and such a document holds nothing of yours to lose: its body is the copy Workover imported from WordPress in the first place.

The test is whether the document has ever been opened in the Workover editor, not whether you changed anything once it was. Opening a document is enough to protect its body from then on.

What a sync overwrites

The title, status, author and publication date come from WordPress every time, for every linked document in the project.

This is the one thing a sync can take from you, and it does it without asking. If you renamed a document in Workover, or moved it through your own workflow — from Triage to In progress, say — a sync sets both back to whatever WordPress says. The document’s status follows the WordPress post’s status: a published post reads as Published here, a draft as Triage, a pending post as Review, a scheduled one as Backlog.

If a title or a workflow state matters, push it to WordPress rather than leaving it to be reconciled, or make the change in WordPress and let the sync bring it back.

A sync will not bring WordPress bodies in

The protection above has a consequence worth knowing: because an opened document keeps its body, a sync will never pull a WordPress change into a document somebody has opened, however many times you press the button. Workover cannot tell whether the body it would replace is your unpushed draft, so it leaves it alone.

This is why a document can sit at New changes in WordPress through repeated syncs. The project sync is not the way to resolve that; opening the document and pulling is, because a pull is the action that warns you before it replaces anything and keeps the previous version in version history. See pulling changes from WordPress.

Permissions

Workover can only do what the WordPress user behind the application password can do. If pushes fail with a permissions error, that user’s role is the first thing to check — an Editor cannot publish others’ posts, and a Contributor cannot publish at all.

Revoking the application password in WordPress cuts the connection immediately and affects nothing already published.