Zero-downtime deployment with Atomic Deployment

View as Markdown

Atomic Deployment updates your application without taking it offline. Buddy uploads the files to a separate directory on the server and switches a symlink to the new version only after the upload has finished.

Configuration

  1. Create a new project and connect it to the repository from which you want to deploy (GitHub, Bitbucket, etc.).
  2. Add a new pipeline and set up the trigger mode and deployment branch:

Image loading...Pipeline configuration

  1. Add a new action, go to the Deploy tab and click Atomic Deployment:

Image loading...Atomic Deployment in the action roster

  1. Read the template description and click Proceed:

Image loading...Atomic Deployment template

  1. In the Target field, select or add an SFTP/SSH target with the access details to your server: address, port, username and authentication method (Inline password, Inline SSH key, or SSH key from Variables, Keys & Assets). You can test the connection before saving. See SSH target for details.
  2. Enter the Target path (required). It overrides the path set in the target.
  3. Select the Source: Buddy Repository deploys files straight from the repository, Pipeline Filesystem deploys the pipeline filesystem, including files created by earlier actions (e.g. compiled assets). Set the Repository path if only a subdirectory should be deployed.
  4. Review the flags: Delete files removed in changeset (enabled by default) removes files deleted from the repository, Upload to temporary file before overwriting previous version replaces each file only after it has fully uploaded, and Always deploy from scratch uploads all files on every run instead of only the changeset.
  5. Optionally, set Ignore files using paths and patterns and The number of versions in the releases directory (10 by default), then click Add this action.
Warning
Point your web server's document root to the current symlink inside the target path, e.g. /var/www/app/current, not to releases/ or deploy-cache/.

How zero-downtime deployments work

Buddy creates two directories and one symlink in the target path:

  • deploy-cache/ - stores the files of the deployment. Buddy uploads only the files that changed since the last deployment and removes the files deleted from the repository.
  • releases/ - contains the history of deployed versions. Each deployment gets its own directory named after the full commit SHA, e.g. releases/f1a5fec316df5a4d55514ee19dae862a5b1404ad.
  • current - a symlink to the active version in the releases/ directory.

Atomic Deployment adds two actions to your pipeline:

Image loading...Atomic deployment actions in the pipeline

  1. Atomic deploy (transfer action) uploads the changes to deploy-cache/.
  2. Post-deployment action

    (SSH action) runs a script on your server that:

    • copies deploy-cache/ to releases/$BUDDY_EXECUTION_REVISION (if a release for that commit already exists, it is reused)
    • points the current symlink to the new release
    • removes old releases and keeps the last 10 by default

The script uses two legacy default variables: $BUDDY_EXECUTION_REVISION (now BUDDY_RUN_COMMIT) contains the full SHA of the deployed commit, and $BUDDY_EXECUTION_REFRESH (now BUDDY_RUN_REFRESH) is true when the files were uploaded from scratch.

The generated pipeline YAML, with the pipeline-scoped target, looks like this:

yaml
- pipeline: Atomic deploy
  refs:
  - refs/heads/main
  targets:
  - target: my-server
    type: SSH
    host: 192.0.2.10
    port: "22"
    path: /var/www/app
    auth:
      method: ASSETS_KEY
      username: deploy
      asset: id_project
  actions:
  - action: Atomic deploy
    type: TRANSFER
    remote_path: /var/www/app/deploy-cache
    targets:
    - my-server
  - action: Post-deployment action
    type: SSH_COMMAND
    working_directory: /var/www/app
    commands: |-
      if [ -d "releases/$BUDDY_EXECUTION_REVISION" ] && [ "$BUDDY_EXECUTION_REFRESH" = "true" ];
      then
       echo "Removing: releases/$BUDDY_EXECUTION_REVISION"
       rm -rf releases/$BUDDY_EXECUTION_REVISION;
      fi

      if [ ! -d "releases/$BUDDY_EXECUTION_REVISION" ];
      then
       echo "Creating: releases/$BUDDY_EXECUTION_REVISION"
       cp -dR deploy-cache releases/$BUDDY_EXECUTION_REVISION;
      fi

      echo "Linking current to revision: $BUDDY_EXECUTION_REVISION"
      rm -f current
      ln -sf releases/$BUDDY_EXECUTION_REVISION current

      echo "Removing old releases"
      cd releases && ls -t | tail -n +11 | xargs rm -rf
    targets:
    - my-server
    run_as_script: true

Where access details are stored

Atomic Deployment stores the server address and credentials in a target, which is pipeline-scoped by default. Both actions use this target, so when the address or credentials change, you edit them in one place. To reuse it across pipelines, change its scope.

Editing atomic deployment

The post-deployment script is an SSH action, so you can change its commands. For example, run database migrations before the symlink switch, or clear the application cache and reload PHP-FPM after it. To keep a different number of releases, change the value in tail -n +11 (the number of releases to keep plus one).

Image loading...Post-deployment action script

You can extend the pipeline, for example compile assets and run tests before the deployment, and send notifications after it:

Image loading...Atomic deployment pipeline example

Last modified on Nov 20, 2026