Skip to content
All posts

· 5 min read · Muhammad Shah

Zero-downtime Laravel deploys to a VPS with GitHub Actions

For Trendivoa, a Laravel 13 and Inertia coupon platform, GitHub Actions builds a release artifact, uploads it to the VPS, prepares a timestamped release and then atomically switches a current symlink. Visitors never see a half-deployed site, and rolling back is one command.

Why not git pull on the server?

Pulling and building in place means the live folder is in a broken state for as long as the build takes, and a failed build can leave it there. It also needs build tools and repository credentials on the server, which expire at the worst moment.

The release layout

/var/www/app
  releases/
    20261101-120000/
    20261101-153000/
  shared/
    .env
    storage/
  current -> releases/20261101-153000

Each deploy gets its own folder. The .env file and storage live in shared/ and are symlinked into every release, so uploads and configuration survive deploys.

The pipeline

  • Run tests and static analysis first; a red build never reaches the server.
  • Install production dependencies and build front-end assets in CI.
  • Upload the archive over SSH with a deploy key, and unpack it into a new release folder.
  • Link shared files, run migrations, warm caches.
  • Switch current to the new release in one atomic step, then reload PHP-FPM and queue workers.
  • Keep the last few releases and delete older ones.
ln -sfn "$RELEASE" "$APP_DIR/current.tmp"
mv -Tf "$APP_DIR/current.tmp" "$APP_DIR/current"

Fail loudly

Start every remote script with set -e. Without it, a failed step can be ignored, the old code gets restarted and the workflow still reports success. I've seen exactly that happen: green checks for weeks while nothing was actually deployed.

Rolling back

Because old releases stay on disk, rollback is just pointing current at the previous folder and reloading services. Practise it once before you need it.