Safe Publish

Safe Publish moves editorial content from a source WordPress site to a destination site over an authenticated connection, preserving the content’s structure and format as closely as possible. It is built for teams that draft, stage, or review content in one environment and need to publish it to another without exporting databases or copying by hand.

This page covers setting up the Integration, browsing and importing content, using Compare, rolling back imports, resolving post-import problems, and how media and audit logging behave. Full developer documentation and the source code are available on GitHub.

How Safe Publish works

Safe Publish runs on both the source and the destination site, with each site assigned a sync mode.

• The source site holds the content to be published. It is usually a non-production environment — staging, a sandbox, or a separate editorial site. The source exposes its content through authenticated REST API endpoints (the catalog).
• The destination site imports content from the source. It is usually the production site. The destination owns the imported posts, media, import history, and audit log.

Content moves in one direction per operation: the destination requests content from the source’s catalog, the source returns it, and the destination creates or updates local posts. Requests between the two sites are signed with a shared secret using Hash-based Message Authentication Code (HMAC) so that only the paired sites can exchange content.

Safe Publish imports content snapshots on demand. It does not run on a schedule, does not sync in real time, and does not copy plugins, themes, or site configuration. It imports only posts, pages, custom post types, their media, and their taxonomy terms.

Key concepts

The plugin uses a small set of terms that are helpful to know.

• Source site — the site content is published from.
• Destination site — the site content is published to. This is the site where the import is performed.
• Sync mode — a per-environment setting that determines whether an environment acts as a source (export), a destination (import), or both (bidirectional). On multisite, it is set per network site.
• Catalog — the list of posts available on the source site, served through a REST API endpoint and browsed from the destination.
• Import — creating a destination draft or updating an existing imported post. A bulk run records several items in one session.
• Compare — a side-by-side comparison of new source content against the current destination post.
• Roll back — reversing the latest eligible import for a selected post. Rolling back a newly created post deletes it. Rolling back an updated post restores the previous content.

In this document, “post” is used in the generic WordPress sense, and includes posts, pages, and custom post types.

Requirements

To use Safe Publish, the following must be in place:

• WordPress 6.8 or higher on both the source and destination sites.
• PHP 8.2 or higher on both sites.
• The Safe Publish Integration enabled on both sites.

The integration creates and sets the shared secret that secures the connection between the sites.

Roles and permissions

Access to every Safe Publish admin screen — browsing source content, importing, reviewing imports and exports, and rolling back — requires the manage_options capability. In a default WordPress installation, only administrators have this capability.

Two further checks apply during an import:

• Updating an existing post requires the edit_post capability for that specific post.
• Comparing an existing post with its source requires the edit_post capability for that post. A direct API caller without manage_options must also have the post type’s edit_posts capability.

The catalog is not filtered per user: everyone who can reach these screens sees all content the source makes available.

Limitations

Safe Publish is scoped to publishing content between two paired sites. The following are not supported:

• Scheduled or automatic sync. Imports are performed manually; there is no cron-based synchronization.
• Real-time, two-way sync. Content moves as on-demand snapshots in one direction per operation, even when both sites are in bidirectional mode.
• Plugin, theme, or configuration transfer. Only content — posts, pages, custom post types, their media, and their taxonomy terms — is imported.
• Third-party media import. Media referenced in post content and hosted off the source domain is left as-is; its URLs are not rewritten or localized. Featured images are an exception: they are downloaded regardless of serving host.
• Importing children of missing parents. By default, importing a child post whose parent is absent on the destination fails, unless safe_publish_import_allow_orphans is enabled.

More Information

• Setting up integration guide enables Safe Publish from the Integration Center in the VIP Dashboard, one environment at a time:
  • Activate the Integration, set the connected application and environment this one exchanges content with, set Sync mode to Import on the destination, leave Use Basic Authentication disabled unless the connected site requires it, and save.
  • The other environment is configured automatically — activating provisions the shared secret that signs requests between the two sites and copies it across, so both ends always hold the same value, and changes take a few minutes to apply.
  • On WordPress multisite, activating at the environment level is not enough: a connection is configured per network site.
• Browsing and managing posts covers what an editor does on the Safe Publish → Manage screen once the Integration is connected:
  • Browsing the source catalog and filtering it by type, title, date, source status, and Local State (All, Not imported, Up to date, Outdated); importing a single post or a bulk selection; previewing a block-by-block Compare before overwriting a destination post; rolling an import back, which deletes a newly created post and restores the previous content of an updated post; and clearing failed and degraded imports from the Needs attention queue with Retry, Ignore, and Remove.
  • It also documents what happens to content in transit — media download, deduplication, and URL rewriting, author attribution by email, audit events, custom post type requirements, and the developer filters.
• Troubleshooting Safe Publish covers the 7 problems Safe Publish reports most often, each with its cause and its fix:
  • A failed authentication or connection check, an import blocked by a missing parent post, an import blocked by a source author that could not be matched or determined, a post type the source does not list in its catalog, a missing raw field value, a rollback that was refused or could not be recorded, and media that did not transfer.