Zero-downtime deployment with Atomic Deployment
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
- Create a new project and connect it to the repository from which you want to deploy (GitHub, Bitbucket, etc.).
- Add a new pipeline and set up the trigger mode and deployment branch:
Image loading...
- Add a new action, go to the Deploy tab and click Atomic Deployment:
Image loading...
- Read the template description and click Proceed:
Image loading...
- 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.
- Enter the Target path (required). It overrides the path set in the target.
- 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.
- 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.
- 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.
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 thereleases/directory.
Atomic Deployment adds two actions to your pipeline:
Image loading...
- Atomic deploy (transfer action) uploads the changes to
deploy-cache/. - Post-deployment action
(SSH action) runs a script on your server that:
- copies
deploy-cache/toreleases/$BUDDY_EXECUTION_REVISION(if a release for that commit already exists, it is reused) - points the
currentsymlink to the new release - removes old releases and keeps the last 10 by default
- copies
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:
- 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...
You can extend the pipeline, for example compile assets and run tests before the deployment, and send notifications after it:
Image loading...
Last modified on Nov 20, 2026