How WordPress sync works
Workover does not host your site or sit in front of it. It talks to WordPress through the WordPress REST API, signed in with the application password you approved when you connected the site. This page explains the model behind pushing, pulling and syncing, so the status labels and warnings you see make sense.
Two copies of each post
When a document is linked to a WordPress post, the content exists twice: once in Workover and once in WordPress. Neither copy is automatically in charge. Three actions move content between them:
| Action | Where | What it does |
|---|---|---|
| Push | WP tab of one document | Sends the Workover version to WordPress and updates the post |
| Pull | WP tab of one document | Replaces the document with the WordPress version |
| Sync from WordPress | Project toolbar | Imports posts Workover does not have yet, and refreshes details of documents it already has |
Workover never merges two edited versions of a body. It tells you which side is ahead and lets you choose. Push and pull only happen when someone selects them. Workover checks your site for changes on its own, and imports new posts on its own (see below).
What Workover tracks
When you push or pull, Workover records when the WordPress post was last modified. It also records the post’s live URL and whether it is published, which is how it knows where a link to that document should point.
Workover then compares that recorded time with the post on WordPress: when you open the WP tab, when you open the project’s document list (at most every 5 minutes per project), and in a background check about every 30 minutes. If the post changed in WordPress since the recorded time, the document shows New changes in WordPress in the WP tab, and a WordPress update pill in the document list. Sync status and conflicts lists every state.
Push and pull in brief
A push sends the body, the title and any WordPress fields you changed in the WP tab. Fields you did not touch are not sent, so a setting you only configured in WordPress survives. Images are uploaded to your media library, and links to other Workover documents are rewritten to their live URLs. See How to push a document to WordPress.
If WordPress changed since your last push or pull, Workover stops the push and asks what to do. See How to fix a push to WordPress that failed.
A pull replaces the document’s body and fields with what is on WordPress. It always asks you to confirm first. See Pulling changes from WordPress.
Some WordPress content, such as custom blocks, ACF blocks and shortcodes, cannot be edited in the Workover editor. When the site lets Workover read a post’s block markup, Workover carries that content through instead of converting it. See Custom blocks and ACF fields.
Syncing a whole project
Sync from WordPress in the project toolbar acts on the whole site at once.
It reads every post type the site makes available through the WordPress REST API, apart from media, menus, templates and reusable blocks. For each post the project has no document for, it creates one. For each post that already has a document, it refreshes that document’s details. Drafts, scheduled, pending and private posts are imported too, not only published ones, as long as the connected WordPress account is allowed to read them. If it is not, only the published posts of that type are imported.
It is safe to select it again. A post that already has a document is matched to it rather than imported a second time. On some sites the import runs in the background, and new documents appear in the list as they arrive.
Workover also runs this import on its own when its background check finds posts on the site that have no document yet.
What a sync overwrites
Warning: A sync replaces each linked document’s title, workflow status, author and publication date with the values from WordPress, without asking. If you renamed a document in Workover, or moved it through your workflow, a sync sets it back. To keep a title or status, push it to WordPress first.
The workflow status follows the WordPress post status:
| WordPress status | Workover status |
|---|---|
| Published | Published |
| Pending review | Review |
| Scheduled | Backlog |
| Draft | Triage |
| Private | Triage |
What a sync protects
A document that has been opened in Workover keeps its body. A sync does not replace its body, and does not touch WordPress field edits you staged but have not pushed yet, such as a slug, an excerpt, categories, tags or SEO fields.
Only a document that has never been opened has its body replaced. Its body is still the copy Workover imported from WordPress, so there is nothing of yours to lose. Opening a document in the editor protects its body from then on, whether or not you change anything. Reading it through the CLI or MCP server counts as opening it too.
The consequence: a sync never brings a WordPress change into a document that has been opened, however many times you run it. That is why a document can keep showing New changes in WordPress after a sync. To bring those changes in, open the document and pull.
Permissions and disconnecting
Workover can only do what the WordPress user behind the application password can do. If pushes fail with a permissions error, check that user’s role first. In WordPress, an Author can only edit and publish their own posts, and a Contributor cannot publish at all.
Revoking the application password in WordPress stops Workover from syncing with the site. Nothing already published changes. Workover emails the workspace owner that it has stopped syncing, and the site needs to be reconnected from Project settings before syncing resumes.
Related
Still need help?
Can’t find what you’re looking for? Our team is here to help.