Git-based content sync for WordPress. Project homepage: https://creativemoods.pt/pushpull/

Will West

What The WP?

Simple audit and traceablity for WordPress DevOps

Jerome Steunenberg

PushPull stores selected WordPress content in a Git repository using a canonical JSON representation instead of raw database dumps.
This project is also documented through a DevOps-focused article series that explains how to efficiently manage a WordPress stack with Bedrock and PushPull, starting here: https://creativemoods.pt/devops-with-wordpress/
<h3>Beta notice</h3>
This is a beta plugin. It is still under active development, has limited functionality, and currently supports only a narrow subset of the intended PushPull feature set.
The current release supports these managed domains:
<ol>
<li>Primary domains: 
 generateblocks_global_styles 
 generateblocks_conditions 
 wordpress_block_patterns 
 wordpress_categories 
 wordpress_comments 
 wordpress_menus 
 wordpress_pages 
 wordpress_posts 
 wordpress_tags 
 wordpress_custom_css 
 generatepress_elements 
 wordpress_attachments (explicit opt-in only) 
generic discovered custom post types and taxonomies</li>
<li>Config domains: 
 wordpress_core_configuration 
 wpml_configuration</li>
<li>Overlay domains: 
 translation_management (WPML-backed) 
 media_organization (Real Media Library-backed)</li>
</ol>
PushPull keeps a local Git-like repository inside WordPress database tables and supports the following workflow directly from WordPress admin:
<ol>
<li>Test the remote GitHub or GitLab connection</li>
<li>Commit live managed content into the local repository</li>
<li>Initialize an empty remote repository</li>
<li>Fetch remote commits into a local tracking ref</li>
<li>Diff live, local, and remote states</li>
<li>Pull remote changes through fetch + merge</li>
<li>Merge remote changes into the local branch</li>
<li>Resolve conflicts when needed</li>
<li>Apply repository content back into WordPress</li>
<li>Push local commits to GitHub or GitLab</li>
</ol>
The plugin also includes:
<ol>
<li>An audit log screen</li>
<li>Local repository reset tooling</li>
<li>Remote branch reset tooling that creates one commit removing all tracked files from the branch</li>
<li>A dedicated Domains screen that separates WordPress core, installed plugin integrations, and discovered custom content</li>
<li>Global and per-domain managed-content views in the admin UI</li>
<li>A high-level PushPull status dropdown in the WordPress admin bar</li>
<li>Menu structure export and apply with hierarchy and theme location assignment</li>
<li>A scheduled lightweight remote-head check that highlights when <code>Fetch</code> likely has updates available</li>
<li>Bulk <code>Commit + Push All</code> and <code>Pull + Apply All</code> workflows for whole-site bootstrap and deploy flows</li>
<li>A <code>wp pushpull</code> WP-CLI command surface for status, configuration, domains, and sync operations</li>
</ol>
<h3>Current scope</h3>
This is an early, focused release. At the moment, PushPull is intentionally limited to:
<ol>
<li>GitHub and GitLab as implemented remote providers</li>
<li>Managed domains across three families: 
 generateblocks/global-styles/ 
 generateblocks/conditions/ 
 wordpress/block-patterns/ 
 wordpress/categories/ 
 wordpress/comments/ 
 wordpress/menus/ 
 wordpress/pages/ 
 wordpress/posts/ 
 wordpress/tags/ 
 wordpress/custom-css/ 
 wordpress/attachments/ 
 wordpress/configuration/ 
 wpml/configuration/ 
 wordpress/generatepress-elements/ 
 wordpress/custom-post-types// 
 wordpress/custom-taxonomies// 
 translations/management/ 
 media/organization/</li>
<li>Canonical JSON storage with one file per managed item for manifest-backed sets, plus directory-backed storage for attachments using <code>attachment.json</code> and the binary file</li>
<li>Explicit opt-in attachment sync through a media-library checkbox</li>
<li>Overlay domains that scope themselves to enabled compatible base domains rather than exporting every backend row blindly</li>
<li>A cached remote-head availability signal for <code>Fetch</code>, driven by a configurable recurring check instead of a live provider probe on every page load</li>
</ol>
It does not yet manage forms, users, arbitrary <code>wp_options</code>, or arbitrary plugin data.
<h3>How PushPull represents content</h3>
PushPull does not use WordPress post IDs as repository identity.
For the currently supported managed sets it stores:
<ol>
<li>One canonical JSON file per managed item</li>
<li>One separate <code>manifest.json</code> file for manifest-backed sets that preserves logical ordering</li>
<li>One directory per attachment for the attachments set, containing <code>attachment.json</code> and the binary file</li>
<li>Stable logical keys instead of environment-specific database IDs</li>
<li>Canonical logical-key references for cross-domain relationships such as reading settings, translation groups, media folders, GeneratePress condition targets, and menu object references</li>
<li>Recursive placeholder normalization for current-site absolute URLs in post-type-backed content</li>
</ol>
<h3>Configuration</h3>
PushPull currently supports GitHub and GitLab repositories.
For GitHub, grant:
<ol>
<li>Repository metadata read access</li>
<li>Repository contents read and write access</li>
</ol>
For GitLab fine-grained personal access tokens, grant:
<ol>
<li><code>Project: Read</code></li>
<li><code>Branch: Read</code></li>
<li><code>Commit: Read</code></li>
<li><code>Commit: Create</code></li>
<li><code>Repository: Read</code></li>
</ol>
In PushPull > Settings:
<ol>
<li>Select <code>GitHub</code> or <code>GitLab</code> as the provider</li>
<li>Enter the repository owner and repository name</li>
<li>Enter the target branch</li>
<li>Enter the API token</li>
<li>Optionally set the remote fetch check interval in minutes</li>
<li>Click <code>Test connection</code></li>
<li>Save the settings</li>
</ol>
<h4>Domain selection</h4>
In PushPull > Domains:
<ol>
<li>Enable one or more managed domains</li>
<li>Review WordPress core, installed plugin integrations, and discovered custom content separately</li>
<li>Opt into generic discovered custom post types and taxonomies when you want them managed</li>
</ol>
<h4>Workflow</h4>
The normal workflow is:
<ol>
<li><code>Commit</code> to snapshot the current live managed-set content into the local repository</li>
<li><code>Fetch</code> to import the current remote branch into <code>refs/remotes/origin/<branch></code></li>
<li>Inspect the live/local and local/remote diff views if needed</li>
<li><code>Pull</code> for the common fetch + merge flow, or <code>Merge</code> manually after fetch when you want review first</li>
<li><code>Apply repo to WordPress</code> when you want the local branch state written back into WordPress</li>
<li><code>Push</code> when you want local commits published to GitHub or GitLab</li>
</ol>
PushPull also performs a lightweight recurring remote-head check and visually highlights <code>Fetch</code> when the latest scheduled check suggests the remote branch has advanced since the last fetch.
For whole-site bootstrap flows, PushPull also supports:
<ol>
<li><code>Commit + Push All</code> to snapshot and publish all enabled domains</li>
<li><code>Pull + Apply All</code> to import and apply all enabled domains on a bare target site</li>
</ol>
If both local and remote changed, PushPull can persist conflicts, let you resolve them in the admin UI, and then finalize a merge commit.
When pushing to GitLab, PushPull currently linearizes local merge results into a normal commit on the remote branch instead of preserving merge topology. The merged tree content is preserved; only the remote Git history shape is flattened.
<h4>WP-CLI</h4>
PushPull also exposes a <code>wp pushpull</code> command.
Examples:
<ol>
<li><code>wp pushpull status</code></li>
<li><code>wp pushpull domains</code></li>
<li><code>wp pushpull config list</code></li>
<li><code>wp pushpull config set branch main</code></li>
<li><code>wp pushpull config enable-domain wordpress_pages</code></li>
<li><code>wp pushpull commit wordpress_pages</code></li>
<li><code>wp pushpull push</code></li>
<li><code>wp pushpull commit-push-all</code></li>
<li><code>wp pushpull pull-apply-all</code></li>
</ol>
<h4>Empty repositories</h4>
If the configured GitHub or GitLab repository exists but has no commits yet, <code>Test connection</code> will report that the repository is reachable but empty.
In that case, click <code>Initialize remote repository</code>. PushPull will:
<ol>
<li>create the first commit on the configured branch</li>
<li>fetch that initial commit into the local remote-tracking ref</li>
<li>make the repository ready for normal commit, fetch, merge, apply, and push workflows</li>
</ol>
You do not need to create the first commit manually on the provider before using PushPull.
<h3>TODO</h3>
<ol>
<li>Cache the admin-bar PushPull status summary so the high-level live/local and local/remote aggregation is not recomputed on every page view.</li>
<li>Move chunked async provider resumability fully into the provider layer so <code>AsyncBranchOperationRunner</code> no longer needs provider-specific GitLab staging rehydration logic.</li>
<li>Improve push progress and recap reporting to distinguish newly uploaded objects from objects reused from the remote history.</li>
<li>Surface unresolved logical-reference mapping issues, such as GeneratePress condition IDs that could not be converted to logical placeholders, instead of silently leaving mixed raw IDs and canonical refs.</li>
</ol>
<h3>External services</h3>
PushPull connects to the GitHub or GitLab API for the repository you configure in the plugin settings.
The plugin uses the provider REST API to:
<ol>
<li>Read repository metadata and the default branch</li>
<li>Read and update branch refs</li>
<li>Read and create Git objects or provider-equivalent commit actions</li>
<li>Test repository access before sync operations</li>
</ol>
PushPull sends the following information to the configured provider over HTTPS:
<ol>
<li>The repository owner, repository name, branch, and API base URL</li>
<li>Your configured API token in the provider-specific authentication header</li>
<li>Canonical JSON representations of the managed content you choose to commit and push</li>
<li>Commit metadata such as commit messages and, if configured, author name and email</li>
</ol>
In the current release, the managed content sent to the provider is limited to the enabled supported domains: GenerateBlocks Global Styles, GenerateBlocks Conditions, WordPress Block Patterns, WordPress Categories, WordPress Comments, WordPress Menus, WordPress Pages, WordPress Posts, WordPress Tags, WordPress Custom CSS, GeneratePress Elements, explicitly opted-in WordPress Attachments, WordPress core configuration, WPML configuration, generic discovered custom post types and taxonomies, WPML-backed translation management, and Real Media Library-backed media organization.
PushPull does not send your whole WordPress database to the provider. It only sends the managed content represented by the enabled adapters.
GitHub terms of service: https://docs.github.com/en/site-policy/github-terms/github-terms-of-service 
GitHub privacy statement: https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement 
GitLab terms: https://about.gitlab.com/terms/ 
GitLab privacy statement: https://about.gitlab.com/privacy/

Alternatives to PushPull

Top alternatives