Deployer tasks and recipes for deploying WordPress sites. Supports simple rsync deployments, custom theme/plugin builds, and complex setups including Bedrock and multisite.
composer require gaambo/deployer-wordpress --dev- Copy example files from
examples/simple/orexamples/bedrock/to your project root - Customize
deploy.phpanddeploy.yml:
- Set
current_pathfor all hosts (remote + localhost) - Configure custom code as packages
- Adjust deployment flow if needed
- Test on staging first, then deploy to production 🚀
This package requires the stable gaambo/deployer-utils:^1.0.1 release.
- PHP 8.3 or newer and Composer
- Deployer 8 (automatically installed)
- WordPress installation
- *nix OS (Linux/macOS or WSL on Windows)
rsyncinstalled
Optional (auto-installed on remote if missing):
- WP-CLI for database tasks
- Composer for package vendors (depending on your custom theme/plugins)
- Node.js/npm for building assets (depending on your custom theme/plugins)
See Upgrading from v4 in the changelog before updating existing projects. It covers PHP/Deployer requirements, helper imports, database and file paths, and WP-CLI runtimes.
Example recipes (in examples/) provide configuration starting points. The library works with any WordPress setup (
vanilla, Composer, subdirectory, Bedrock, multisite) by making all paths and directories configurable. Check the example
recipes and task source files for available options.
Configure localhost in deploy.php:
localhost()
->set('public_url', 'http://wp-boilerplate.test')
->set('deploy_path', __DIR__)
->set('current_path', '{{deploy_path}}/public') // WordPress root
->set('dbdump_path', 'data/db_dumps')
->set('backup_path', __DIR__ . '/data/backups');deploy_path is the project root and is used for private data such as relative database dump paths. current_path is
the WordPress root. The previous project_path example setting was unused and has been removed.
Local and remote WP-CLI database commands honor runtimes configured on their source hosts and map database dump paths
into them. See the
Deployer Utils README for generic localhost, runtime, Composer, npm,
file, and rsync APIs. The old Gaambo\DeployerWordpress helper names remain as deprecated wrappers for migration.
Keep wp-config.php in git and deploy it. Extract environment-specific config (database credentials, WP_DEBUG) into
wp-config-local.php, which should be gitignored and created manually on each host. Require it from wp-config.php:
if (file_exists(__DIR__ . '/wp-config-local.php')) {
require_once __DIR__ . '/wp-config-local.php';
}The default rsync config uses .deployfilter files for per-directory filtering. Place a .deployfilter file in your
theme/plugin to exclude development files:
- phpcs.xml
- README.md
- .babelrc
- node_modules
- .eslintignore
- .eslintrc.json
- .stylelintignore
- .stylelintrc.json
- gulp.config.js
- gulpfile.babel.js
- package.json
- package-lock.json
- .babelrc
- phpcs.xml
This prevents any development files/development tools from syncing. I strongly recommend you put something like this in
your custom theme and mu-plugins or overwrite any of the themes/filter or mu-plugins/filter configurations.
Tasks are in the tasks/ directory. Run dep list to see all available tasks. See task source files for configuration
options.
db:remote:backup: Backup remote database and download to localhostdb:local:backup: Backup local database and upload to remote hostdb:remote:import: Import current database backup (from localhost) on remote hostdb:local:import: Import current database backup (from remote host) on local hostdb:push: Pushes local database to remote host (combinesdb:local:backupanddb:remote:import)db:pull: Pulls remote database to localhost (combinesdb:remote:backupanddb:local:import)
For multisite installations, set wp/multisite to true to enable network-wide search-replace during database sync:
set('wp/multisite', true);Manage custom themes, plugins, and mu-plugins with individual build configs:
set('packages', [
'custom-theme' => [
'path' => '{{themes/dir}}/custom-theme',
'remote:path' => '{{themes/dir}}/custom-theme', // optional
'assets' => true,
'assets:build_script' => 'build',
'vendors' => true, // Run composer install
],
// Add more packages as needed
]);Tasks:
packages:assets:vendors- Install npm dependenciespackages:assets:build- Run build scriptspackages:vendors- Install composer dependenciespackages:push/packages:pull- Sync packages
File Tasks (tasks/files.php)
files:push/files:pull- Sync all files (combines wp, uploads, plugins, themes, packages)files:backup:remote/files:backup:local- Back up all files through the shared utils tasks
WordPress Core (tasks/wp.php)
wp:download-core,wp:push,wp:pull,wp:info
Languages (tasks/languages.php)
languages:push,languages:pull,languages:sync,languages:backup:*
Uploads (tasks/uploads.php)
uploads:push,uploads:pull,uploads:sync,uploads:backup:*
Legacy Tasks (use packages instead)
- Themes:
themes:push,themes:pull - Plugins:
plugins:push,plugins:pull - MU-Plugins:
mu-plugins:push,mu-plugins:pull
Like v4, v5 uses current_path for rsync-based deployments. Symlinked releases are still possible but not the default.
recipes/simple.php - Standard WordPress. Rsyncs directly to current_path. Recommended for most projects.
recipes/bedrock.php - Roots Bedrock projects with appropriate structure and
environment handling.
See CHANGELOG.md.
Issues, feature requests, and pull requests welcome at GitHub. Code follows PSR-12 and Deployer best practices.
The library includes a comprehensive test suite with unit, integration, and functional tests.
- Run
composer precommitbefore submitting a PR — it runs lint, code style, PHPStan, strict Composer validation, and all tests. - Functional tests use a mocked environment to verify rsync commands and file operations without real remote connections.
- Tests load shared support classes from
deployer-utils/tests/throughautoload-dev. They rely on those files shipping in Utils distribution archives, as documented in its shared test support API.
CI tests Deployer 8 on PHP 8.3, 8.4, and 8.5.