DevOps
A Safe WordPress Deployment Workflow
A release workflow for WordPress code, configuration, database changes, media, rollback, verification, and operational ownership.
Author: Fahad Bin Shakir · Published: · Updated: · 12 min read
Introduction
A WordPress deployment combines application code, plugins, themes, configuration, a mutable database, scheduled work, and user-generated media. Treating it as a file upload misses the state transitions that make releases risky. A safe workflow identifies which parts are versioned, which are environment-specific, and which can change while a deployment is in progress.
The objective is a repeatable release with a known artifact, a compatible migration path, observable health checks, and a rollback decision that does not depend on improvisation.
Define ownership of every stateful surface
Keep custom themes, custom plugins, must-use plugins, dependency manifests, server configuration templates, and deployment scripts in version control. Keep secrets, generated caches, and environment-specific runtime values outside the repository. Decide how plugin and core versions are pinned; updating through the production dashboard undermines reproducibility unless that change is immediately reconciled with the declared release source.
Treat uploads and the database as durable state, not build artifacts. Define one writer during a migration window, and understand whether editors, orders, form submissions, or scheduled jobs can change data while files are being switched. Maintenance mode is one option, but short backward-compatible migrations often provide a better user experience.
Build and test an immutable release artifact
Create the deployable artifact in continuous integration from a reviewed commit. Install production dependencies from lockfiles, compile assets, remove development files, scan for secrets, and record a checksum. The server should receive that artifact instead of running an undocumented sequence of manual edits.
Test the artifact against a representative staging copy with sanitized data. Verify PHP compatibility, plugin activation, cron, permalinks, forms, authentication, media, search, caching, and critical integrations. A staging success is meaningful only when its PHP extensions, web server behavior, and configuration resemble production.
Make database changes backward compatible
Schema and data changes are the hardest part to roll back. Prefer an expand-and-contract sequence: add new structures first, deploy code that can work with both versions, migrate data in bounded batches, then remove old structures in a later release. Avoid long locks and unbounded updates during the request path.
Back up before a risky migration and perform a restore rehearsal before relying on that backup. A dump that has never been restored is an assumption. Record the database engine, character set, storage location, encryption, retention, and restoration command in the runbook.
Switch releases atomically
Deploy each version to a separate release directory, connect shared media and environment configuration, warm required caches, and change a symlink or platform release pointer only after preflight checks pass. This reduces the interval in which visitors can receive a mixture of old and new files.
Coordinate cache invalidation with the switch. Hashed assets can remain immutable, while HTML and application caches should be purged or versioned. Do not delete the previous release immediately; retain enough versions for a rapid code rollback while respecting disk and secret hygiene.
Verify outcomes, not just command exit codes
Run smoke tests through the public domain after deployment: homepage, representative content, login, API or AJAX endpoints, form validation, media, sitemap, robots, canonical tags, and an unknown route. Check the error log, response time, queue or cron health, and third-party integration failures.
Define rollback thresholds before release. If errors, latency, checkout failures, or editorial failures cross the threshold, stop and revert the release pointer. A database rollback may be unsafe after new writes, so the code rollback must often remain compatible with the expanded schema.
Control emergency changes
Production hotfixes sometimes happen, but they should enter the same history as normal work. Capture the exact change, review it, deploy a replacement artifact, and remove temporary access. Do not let a one-line dashboard edit become an invisible fork of production.
After the incident, record the detection gap, why the standard path was too slow, and which automation or alert should change. A release process improves when exceptions generate engineering work instead of permanent exceptions.
Deployment checklist
- Version custom code and pin production dependencies.
- Build one reviewed, checksummed release artifact.
- Rehearse on representative infrastructure and sanitized data.
- Use backward-compatible database migrations and tested backups.
- Switch releases atomically and coordinate cache invalidation.
- Run public-domain smoke tests and observe logs after release.
- Define rollback thresholds and retain a compatible previous release.
- Reconcile every emergency change into version control.