Zero-downtime WordPress deploys with GitHub Actions and atomic symlinks

A build-once, release-atomically pipeline for WordPress: what goes in the artifact, how releases switch, and how to roll back in under two seconds.

Most WordPress deploy setups I inherit fall into one of two camps: FTP uploads, or a git pull on the production server. Both leave the site in a half-updated state for some window of time, and neither has a real rollback.

This article walks through the pipeline I use on client and personal projects. It builds the artifact once in CI, ships it to a new release directory, and switches traffic with a single symlink change.

Why atomic releases

A deploy is atomic when users see either the old version or the new version, never a mix.

  • Each release lives in its own timestamped directory.
  • current is a symlink to the active release.

note

Something the reader should know before going on.

The pipeline

The workflow has two jobs. verify runs on every pull request; deploy runs only on main.

Building the artifact

Build once, deploy that exact artifact everywhere.

deploy.php
namespace Deployer;

require 'recipe/common.php';

set('keep_releases', 5);
set('shared_dirs', ['web/sites/alexbertens.com/files/uploads']);

after('deploy:symlink', 'opcache:reset');

Switching the release

Deployer uploads to a new release directory, links shared paths, runs a health check, and only then moves the symlink.

Database changes

Code rolls back instantly; schemas don’t. Every database change ships in two releases.

warning

Something that can go wrong, and how to avoid it.

Rolling back

Because the previous five releases are still on disk, a rollback is just pointing the symlink back:

$ dep rollback production
✔ Rolled back to release 20261020T0912 (1.4s)

That’s the whole pipeline.