1. Install a pinned version of the binary at the start of the job, so that a new release never changes your pipeline unexpectedly.
2. Provide secrets through the environment. There is no terminal to answer a prompt: map your CI secrets to AUTOMATE__<name> variables, or pass them with --var. See Variables.
3. Use --no-interaction so that any missing value fails the job instead of hanging on a prompt.

Private keys stored as secrets must be written to a file, since ssh_key expects a path.

GitHub Actions

This workflow deploys main to staging on every push, and tags to production.

# .github/workflows/deploy.yml
name: Deploy

on:
    push:
        branches: [main]
        tags: ['*']

concurrency: deploy-${{ github.ref_name }}

jobs:
    deploy:
        runs-on: ubuntu-latest
        env:
            AUTOMATE_VERSION: 4.2.2
        steps:
            - uses: actions/checkout@v4

            - name: Install Automate
              run: |
                  curl -LSs -o /usr/local/bin/automate \
                      "https://github.com/automatephp/automate/releases/download/${AUTOMATE_VERSION}/automate-linux-amd64"
                  chmod +x /usr/local/bin/automate
                  automate --version

            - name: Write the SSH key
              run: |
                  install -m 600 /dev/null /tmp/deploy_key
                  echo "${{ secrets.DEPLOY_SSH_KEY }}" > /tmp/deploy_key

            - name: Deploy to staging
              if: github.ref == 'refs/heads/main'
              run: automate deploy staging --no-interaction

            - name: Deploy to production
              if: startsWith(github.ref, 'refs/tags/')
              run: automate deploy production "${{ github.ref_name }}" --no-interaction
              env:
                  AUTOMATE__prod_password: ${{ secrets.PROD_PASSWORD }}

With the matching configuration:

platforms:
    staging:
        default_branch: main
        servers:
            staging-01:
                host: staging.acme.io
                user: deploy
                ssh_key: /tmp/deploy_key
                path: /var/www/shop
    production:
        default_branch: main
        servers:
            web-01:
                host: web-01.acme.io
                user: deploy
                password: "%prod_password%"
                path: /var/www/shop

The concurrency key makes GitHub queue the deployments of the same reference. Automate also protects the servers with its own lock file, so two overlapping jobs cannot corrupt a release.

Building in CI and uploading

When the servers should not build the application, build it in the job and upload the result. Leave repository unset, or keep it and upload only the generated files (see Deployment strategies).

            - uses: actions/setup-node@v4
              with:
                  node-version: 22
                  cache: npm
            - run: npm ci && npm run build

            - name: Deploy
              run: automate deploy production --no-interaction

# .automate.yml
repository: git@github.com:acme/shop.git

pre_deploy:
    - upload: public/build

GitLab CI

# .gitlab-ci.yml
stages: [build, deploy]

variables:
    AUTOMATE_VERSION: "4.2.2"

.automate:
    image: ubuntu:24.04
    before_script:
        - apt-get update -qq && apt-get install -y -qq curl ca-certificates
        - curl -LSs -o /usr/local/bin/automate "https://github.com/automatephp/automate/releases/download/${AUTOMATE_VERSION}/automate-linux-amd64"
        - chmod +x /usr/local/bin/automate
        - install -m 600 /dev/null /tmp/deploy_key
        - echo "$DEPLOY_SSH_KEY" > /tmp/deploy_key

deploy:staging:
    extends: .automate
    stage: deploy
    script:
        - automate deploy staging --no-interaction
    rules:
        - if: $CI_COMMIT_BRANCH == "main"
    environment:
        name: staging
        url: https://staging.acme.io

deploy:production:
    extends: .automate
    stage: deploy
    script:
        - automate deploy production "$CI_COMMIT_TAG" --no-interaction
    rules:
        - if: $CI_COMMIT_TAG
    environment:
        name: production
        url: https://www.acme.io
    when: manual

Declare DEPLOY_SSH_KEY and the AUTOMATE__* passwords as masked CI/CD variables in the project settings. A variable named AUTOMATE__prod_password is picked up directly, with no extra mapping.

Review environments

Combine variables with automate remove to create one environment per branch and tear it down when the branch is closed:

# .automate.yml
platforms:
    review:
        default_branch: main
        servers:
            vm:
                host: review.acme.io
                user: deploy
                ssh_key: /tmp/deploy_key
                path: /srv/review/%slug%

deploy:review:
    extends: .automate
    stage: deploy
    script:
        - automate deploy review "$CI_COMMIT_REF_NAME" --var slug="$CI_COMMIT_REF_SLUG" --no-interaction
    environment:
        name: review/$CI_COMMIT_REF_SLUG
        url: https://$CI_COMMIT_REF_SLUG.review.acme.io
        on_stop: stop:review
    rules:
        - if: $CI_MERGE_REQUEST_ID

stop:review:
    extends: .automate
    stage: deploy
    script:
        - automate remove review --var slug="$CI_COMMIT_REF_SLUG" --yes --no-interaction
    environment:
        name: review/$CI_COMMIT_REF_SLUG
        action: stop
    rules:
        - if: $CI_MERGE_REQUEST_ID
          when: manual

Other runners

Any runner works the same way: download the binary (or the PHAR with PHP 8.4+), export the AUTOMATE__* variables, run automate deploy. On macOS runners, use the automate-darwin-arm64 binary.

Common options

These options are accepted by every command:

deploy

automate deploy <platform> [<gitRef>] [--force] [-c <file>] [--var name=value]

Deploys the platform on all its servers. See the Deployment lifecycle.

automate deploy production
automate deploy production v1.4.0
automate deploy staging feature/checkout -c deploy/.automate.yml
automate deploy review my-branch --var slug=my-branch

The command prints a summary (repository, platform, servers, version, variable names), then each step with the output of the commands prefixed by the server name. It exits with a non-zero status when the deployment fails.

rollback

automate rollback <platform> [<release>] [--yes] [--force] [-c <file>] [--var name=value]

Points current back to a previous release on every server of the platform, without cloning or building anything. The command shows the servers and the targeted release, then asks for confirmation. See Rolling back.

automate rollback production
automate rollback production 2026.10.22-1805.341
automate rollback production --yes

On each server, Automate switches current to the target release, runs the post_rollback hooks in it, then moves the release that was left to releases/failed, where it stays for inspection until the next deployment.

• Nothing is changed unless every server has a valid target: current must point to one of the listed releases, the target must exist on the server, and without an explicit release all the servers must agree on the previous one. Otherwise the command stops and asks for an explicit release.
• If a post_rollback command fails, current has already been switched, the release that was left stays in releases/, and the command exits with a non-zero status.
• Since the release that was left is no longer listed, a second rollback goes one release further back.

check

automate check <platform> [-c <file>] [--var name=value]

Connects to every server of the platform and runs git ls-remote <repository> from there. Use it after writing a configuration, or to diagnose a failing deployment: a wrong password, an unreachable host or a missing deploy key are reported without touching the server.

automate check production

exec

automate exec <platform> <server> "<command>" [--current] [-c <file>] [--var name=value]

Runs a single command on one server of the platform and prints its output.

Without --current, the command runs as is, from the home directory of the SSH user:

automate exec production web-01 "df -h /var/www"
automate exec production web-01 "ls -la /var/www/shop/releases"

With --current, it runs in the published release, which is convenient to replay a hook or to run a console command:

automate exec production web-01 "php bin/console cache:clear" --current
automate exec production web-01 'echo $AUTOMATE_RELEASE_ID' --current

remove

automate remove <platform> [--yes] [--force] [--keep-shared] [-c <file>] [--var name=value]

Removes the project from every server of the platform, for example to clean up a review environment. The command shows what will be removed and asks for confirmation.

On each server, Automate runs the on_remove hooks in the current release, then deletes the releases folder, the current link and the shared folder, and finally the project path itself when nothing else is left in it.

automate remove review --var slug=my-branch --yes

• A shared_path located outside of the project path is never deleted, since other projects may use it.
• If an on_remove command fails, nothing is deleted on any server.
• The command can be run again safely: when the project path does not exist, there is nothing to remove.

Complete example

repository: git@github.com:acme/shop.git

platforms:
    staging:
        default_branch: develop
        max_releases: 3
        servers:
            staging-01:
                host: staging.acme.io
                user: deploy
                password: "%staging_password%"
                path: /var/www/shop
                port: 2222
    production:
        default_branch: main
        max_releases: 5
        servers:
            web-01:
                host: web-01.acme.io
                user: deploy
                ssh_key: /home/me/.ssh/id_ed25519
                password: "%key_passphrase%"
                path: /var/www/shop
            web-02:
                host: web-02.acme.io
                user: deploy
                ssh_key: /home/me/.ssh/id_ed25519
                path: /var/www/shop
                shared_path: /mnt/nfs/shop-shared

shared_files:
    - .env.local

shared_folders:
    - var/uploads
    - var/log

pre_deploy:
    - upload: public/build

on_first_deploy:
    - 'cp .env.dist "$AUTOMATE_SHARED_PATH/.env.local"'

on_deploy:
    - composer install --no-dev --optimize-autoloader
    - php bin/console cache:warmup

post_deploy:
    - cmd: php bin/console doctrine:migrations:migrate -n
      only: [web-01]
    - sudo systemctl restart shop-worker

on_remove:
    - sudo systemctl stop shop-worker

post_rollback:
    - sudo systemctl restart shop-worker

Root options

Hooks are described in detail on the Hooks page.

repository

repository: git@github.com:acme/shop.git      # SSH
repository: https://github.com/acme/shop.git  # HTTPS, for a public repository

The clone runs on the server, so the server needs access to the repository, for example with a deploy key. The clone is recursive: submodules are included.

shared_files and shared_folders

shared_files:
    - .env.local
    - config/jwt/private.pem

shared_folders:
    - var/uploads
    - var/sessions

Paths are relative to the release root. On every deployment, each entry is replaced in the release by a symbolic link to the same path under shared/. The first deployment moves the file or folder from the release to shared/ when it exists there; otherwise an empty file or folder is created. Intermediate directories are created as needed.

Platforms

A platform is a named group of servers deployed together, such as staging or production.

platforms:
    production:
        default_branch: main
        max_releases: 5
        servers:
            web-01: { host: web-01.acme.io, user: deploy, ssh_key: /home/me/.ssh/id_ed25519, path: /var/www/shop }
            web-02: { host: web-02.acme.io, user: deploy, ssh_key: /home/me/.ssh/id_ed25519, path: /var/www/shop }

Server names are used by the only option of actions, by the exec command and in the console output. Keep them short and unique within the platform.

Servers

Authentication

Automate authenticates with a password or with a private key:

servers:
    with-password:
        host: web-01.acme.io
        user: deploy
        password: "%prod_password%"
        path: /var/www/shop
    with-key:
        host: web-02.acme.io
        user: deploy
        ssh_key: /home/me/.ssh/id_ed25519
        password: "%key_passphrase%"   # only if the key is encrypted
        path: /var/www/shop

Automate reads the key file itself; the SSH agent and ~/.ssh/config are not used. Give the absolute path of the key. In CI, write the key from a secret to a file before running Automate (see CI integration).

A password written as %name% is a variable: Automate reads it from --var name=..., then from the AUTOMATE__name environment variable, and finally prompts for it in the terminal. See Variables.

Local transport

With transport: local, the server is the machine that runs Automate. No SSH connection is made: commands run directly through /bin/sh, and uploads are copied on the file system. Use it to deploy on the host itself, for example from a CI runner that sits on the target machine, or to try Automate without a remote server.

platforms:
    production:
        default_branch: main
        servers:
            self:
                transport: local
                path: /var/www/shop

Commands run as the user who launches Automate and inherit its environment. The host, user, password and ssh_key options are rejected with the local transport, since Automate cannot switch user: run Automate as the user who must own the releases.

All the commands work with a local server: deploy, rollback, check, remove and exec --current. The local transport needs a POSIX system (Linux, macOS); it does not work when Automate itself runs on Windows.

Validation

The configuration is validated when a command starts. Unknown options, a missing path or a platform without servers stop the command with a message naming the faulty key, for example:

Unrecognized option "shared_file" under "automate". Available options are "on_deploy", "on_first_deploy", ...

Directory layout

Under the path configured for a server, Automate maintains three entries:

/var/www/shop
├── automate.lock                      # only while a deployment runs
├── current -> releases/2026.10.23-1412.587
├── releases
│   ├── 2026.10.21-0930.112
│   ├── 2026.10.22-1805.341
│   ├── 2026.10.23-1412.587
│   └── failed                         # the last failed or rolled back release, if any
└── shared
    ├── .env.local
    └── var/uploads

Steps of a deployment

Automate opens a session with every server of the platform, then runs the following steps. Each step completes on every server before the next one starts, and a failure at any step stops the deployment on all servers.

1. Connect and detect first deployments. A server with no release in its releases folder is in its first deployment, which enables the on_first_deploy hooks for that server.
2. Lock. automate.lock is created in path. If it already exists, the deployment stops with A deployment, a removal or a rollback is already in progress, unless --force is given. Any previous releases/failed folder is removed.
3. Create the release folder releases/<release id>.
4. Clone the repository, when repository is set: git clone <repository> -q --recursive -b <default_branch> ., followed by a git checkout of the branch, tag or commit given to deploy. A reference that matches a tag is checked out as tags/<ref>. Without repository, the release folder stays empty: your pre_deploy hooks are expected to upload the application.
5. pre_deploy hooks run in the release folder.
6. Shared items. Each entry of shared_files and shared_folders is replaced in the release by a symbolic link to shared/. On the first deployment, a file or folder present in the release is moved to shared/ first; otherwise an empty file or folder is created there.
7. on_first_deploy hooks run, only on the servers in their first deployment.
8. on_deploy hooks run in the release folder. This is where you build the application: install dependencies, compile assets, warm up caches.
9. Publish. current is pointed to the new release with ln -sfn. From this moment, the new release is live.
10. post_deploy hooks run in the new release: migrations, cache clearing, restarting workers.
11. Clean up. Releases beyond max_releases are removed, oldest first. The release that current points to is never removed; releases/failed and any folder that does not look like a release id are ignored.
12. Unlock. automate.lock is removed.

Which hook should I use? Anything that must be ready before the release goes live belongs in on_deploy. Anything that acts on the live application, such as database migrations or process restarts, belongs in post_deploy. See Hooks for details and the environment variables available to your commands.

Multiple servers

Commands run in parallel on all the servers of the platform, each one in its own SSH session. The output is prefixed with the server name. If a command fails on one server, the deployment stops once the command completed on the others; the release is never published anywhere, because publishing comes after all the build hooks.

Use the only option of an action to run it on a subset of servers, typically to run a database migration once:

post_deploy:
    - cmd: php bin/console doctrine:migrations:migrate -n
      only: [web-01]

When a deployment fails

• Before publishing (steps 2 to 8): the release is moved to releases/failed, current still points to the previous release, and the lock is released. Nothing changed for your users. Inspect releases/failed, fix the problem and deploy again.
• After publishing (post_deploy): the new release stays live, since it was already switched. The deployment is reported as failed, the lock is released, and the release is kept. Run the failing command again with automate exec --current, or deploy a fix.

Rolling back

Publishing is a symbolic link, so rolling back is pointing current to a previous release. The releases kept by max_releases are intact, including their shared links, and automate rollback switches to one of them on every server:

automate rollback production                        # the release before the current one
automate rollback production 2026.10.22-1805.341    # a given release

On each server, the command:

1. Locks the project with automate.lock, as a deployment does.
2. Checks the target. current must point to one of the listed releases and the target must exist. Without an explicit release, every server must agree on the previous one; otherwise nothing is changed and the command asks for an explicit release.
3. Publishes the target release with ln -sfn.
4. Runs the post_rollback hooks in the restored release, with the same environment as the deployment hooks and AUTOMATE_PHASE=rollback.
5. Sets aside the release that was left by moving it to releases/failed, where it can be inspected until the next deployment removes it. Since it is no longer listed, it will not be picked by max_releases over an older, working release, and a second rollback goes one release further back.
6. Unlocks.

If a post_rollback command fails, current already points to the restored release and the release that was left stays in releases/.

Remember to revert any post_deploy effect that is not backward compatible, such as a database migration, for example in a post_rollback hook.

Locking

The lock is per server, in the path directory. A lock left behind by a crashed process or a lost connection makes every later deployment fail with A deployment, a removal or a rollback is already in progress. When you are sure no deployment is running, deploy with --force, which ignores the existing lock, or remove the file:

automate exec production web-01 "rm /var/www/shop/automate.lock"

Git deployment

Set repository. On each server, Automate clones the repository into the new release, checks out the requested reference and runs your hooks there. This is the simplest setup: the server does everything.

repository: git@github.com:acme/shop.git

on_deploy:
    - composer install --no-dev --optimize-autoloader
    - yarn install --frozen-lockfile
    - yarn build

post_deploy:
    - cmd: php bin/console doctrine:migrations:migrate -n
      only: [web-01]

The server must be able to reach the repository, usually with a deploy key, and must have the build tools installed: composer, node, and so on. automate check <platform> verifies the repository access from each server.

The clone uses --recursive, so Git submodules are checked out too.

CI build and upload

Leave repository unset. Build the application in your CI pipeline, then upload the result with an upload action in pre_deploy. The server only receives files and runs the commands that must happen there, such as a database migration.

# no "repository" key

pre_deploy:
    - upload: .
      exclude: [node_modules, .git, tests]

post_deploy:
    - cmd: php bin/console doctrine:migrations:migrate -n
      only: [web-01]

Each upload packs the local path in a tar.gz archive, sends it to the release folder of every server (or of the servers listed in only), and extracts it there. See Upload actions for the exclude syntax.

This strategy keeps the servers minimal and makes the deployed artifact identical on every server, since it is built once.

Mixed deployment

Set repository and upload what the CI built. Automate clones the source on the server, then your pre_deploy upload adds the generated files, for example the compiled assets, on top of it.

repository: git@github.com:acme/shop.git

pre_deploy:
    - upload: public/build

on_deploy:
    - composer install --no-dev --optimize-autoloader

post_deploy:
    - cmd: php bin/console doctrine:migrations:migrate -n
      only: [web-01]

This keeps the Git history and the PHP build on the server, while sparing it from installing Node and compiling assets.

Deploying on the local machine

With transport: local, a server is the machine that runs Automate itself: no SSH is involved, commands run directly and uploads are plain file copies. The three strategies above work the same way. See Local transport.

The full sequence is described in the Deployment lifecycle.

Actions

An action is a command or an upload. A plain string is a command:

on_deploy:
    - composer install --no-dev
    - cmd: yarn build
    - upload: public/build

Commands

post_deploy:
    - cmd: php bin/console doctrine:migrations:migrate -n
      only: web-01
    - cmd: php bin/console messenger:stop-workers
      only: [web-01, web-02]

The command fails, and so does the deployment, when it exits with a non-zero status. Its output is printed under the server name.

Tip: long scripts are easier to maintain in a file committed with the project: - bash deploy/after-publish.sh. The script receives the hook environment.

Upload

An upload action sends a local file or directory to the release folder of the servers. The path is read on the machine that runs Automate, relative to the current directory, and recreated at the same relative path in the release.

pre_deploy:
    - upload: .
      exclude:
          - node_modules
          - .git
          - '/^tests\//'
    - upload: public/build
      only: [web-01]

Automate packs the files in a tar.gz archive, sends it to each server and extracts it in the release folder. Each exclude entry is matched against the path of every file, relative to the uploaded directory:

• a plain string excludes every path that contains it: node_modules drops that folder wherever it appears;
• a regular expression, with its delimiters, is matched against the same relative path: '/^tests\//' only drops the tests folder at the root of the upload. Escape the delimiter inside the expression: '/^folder/subfolder/' is not a valid pattern and is rejected.

upload is not allowed in on_remove and post_rollback.

First deployment

A server is in its first deployment when its releases folder contains no release. A release moved to releases/failed does not count, so the next attempt is still a first deployment. The detection is made per server: on a platform with one new server and one already deployed, only the new one runs on_first_deploy, and only can restrict it further.

Since the links to shared/ already exist at that point, the hook can create the files that later deployments will find in place:

on_first_deploy:
    - 'cp .env.dist "$AUTOMATE_SHARED_PATH/.env.local"'
    - php bin/console doctrine:database:create

Any command can also test the AUTOMATE_FIRST_DEPLOY variable, for example in post_deploy:

post_deploy:
    - 'if [ "$AUTOMATE_FIRST_DEPLOY" = 1 ]; then php bin/console doctrine:fixtures:load -n; fi'

Removal hook

on_remove lists the commands run by automate remove in the current release, before anything is deleted. Use it to stop what the project started: containers, cron jobs, workers.

on_remove:
    - docker compose down --volumes
    - cmd: crontab -r
      only: [web-01]

If a command fails, nothing is deleted on any server. The hook is skipped on a server that has no current release.

Rollback hook

post_rollback lists the commands run by automate rollback in the restored release, after current has been switched back to it and before the release that was left is moved to releases/failed. Use it to reload or restart what runs the code: PHP-FPM, workers, a Node server.

post_rollback:
    - cmd: php bin/console messenger:stop-workers
      only: [web-01]

If a command fails, the rollback is reported as failed: current already points to the restored release, and the release that was left stays in releases/.

Hook environment

Every command runs with these environment variables, so scripts can locate the release and the shared folder without hard-coding paths:

During on_remove, post_rollback and exec --current, the AUTOMATE_RELEASE_* variables describe the release that current points to.

post_deploy:
    - 'echo "Deployed $AUTOMATE_GIT_REF to $AUTOMATE_SERVER" >> "$AUTOMATE_SHARED_PATH/deployments.log"'

Install script

curl -LSs https://www.automate-deployer.com/install | bash

The script:

1. checks that curl or wget is available;
2. detects your operating system and architecture;
3. downloads the latest release from GitHub Releases;
4. installs it as /usr/local/bin/automate when run as root, or as ~/.automate/bin/automate otherwise.

When installed in your home directory, add it to your PATH or move it to a system directory:

sudo mv ~/.automate/bin/automate /usr/local/bin/automate

Then check the installation:

automate --version

Upgrading: run the install script again. It always downloads the latest release and replaces the binary.

Supported platforms

Manual download

Every release publishes the binaries on GitHub. Download the one for your platform, make it executable and move it to your PATH:

sudo curl -LSs -o /usr/local/bin/automate https://github.com/automatephp/automate/releases/latest/download/automate-linux-amd64
sudo chmod +x /usr/local/bin/automate

Give the output file a path that does not already exist as a directory: -o automate fails with Failure writing output to destination when run next to a folder named automate, such as a clone of the repository.

To pin a specific version, replace latest/download with download/<version>:

sudo curl -LSs -o /usr/local/bin/automate https://github.com/automatephp/automate/releases/download/4.2.2/automate-linux-amd64

Pinning is recommended in CI pipelines so that a new release never changes a build unexpectedly.

PHAR

The PHAR requires PHP 8.4 or later. The openssl and gmp (or bcmath) extensions are recommended: they make the SSH key exchange much faster.

curl -LSs -o automate.phar https://github.com/automatephp/automate/releases/latest/download/automate.phar
php automate.phar --version

You can also make it executable and move it to your PATH as automate.

Shell completion

Automate is built with the Symfony Console component and supports its completion script. It needs a release newer than 4.2.2: older binaries do not embed the completion scripts and report supported shells: "".

automate completion bash > /etc/bash_completion.d/automate   # bash
automate completion zsh > "${fpath[1]}/_automate"             # zsh

Every deployment creates a new, isolated release on each server. When all your build steps succeed, a current symbolic link is switched to the new release. Your web server always points to current, so visitors never see a half-deployed application, and a failed deployment never goes live.

Features

• Atomic, zero-downtime releases. Each deployment lives in its own timestamped folder; publishing is a single symlink switch, and so is rolling back with automate rollback.
• Multi-server platforms. Deploy to one server or to a whole fleet. Hooks run in parallel on every server, and any command can be restricted to a subset with only.
• Shared files and folders. Keep .env.local, uploads or caches across releases: Automate links them into every new release.
• Git, CI build, or both. Clone the repository on the server, upload the artifacts built by your CI, or mix the two. See Deployment strategies.
• Hooks at every stage. Run commands before the release is prepared, on the first deployment of a server, before publishing, after publishing, after a rollback, and when a project is removed. See Hooks.
• Secrets from the environment. Passwords and other values are resolved from --var options or AUTOMATE__* environment variables, and masked in the output. See Variables.
• Safe by default. A lock file prevents two deployments from overlapping, failed releases are set aside, and old releases are pruned automatically.
• Any stack. PHP, Node, Ruby, Python, static sites: if it runs on a Linux server, Automate can deploy it. Automate itself is a single static binary with no runtime dependency.

How it works

$ automate deploy production

 Start deployment
 ----------------
 ------------ -----------------------------------
  Repository   git@github.com:acme/shop.git
  Platform     production
  Servers      web-01 (web-01.acme.io)
               web-02 (web-02.acme.io)
  Version      main
 ------------ -----------------------------------

 Prepare Release
 ---------------
 git clone git@github.com:acme/shop.git -q --recursive -b main .

 Setting up shared items
 -----------------------
 [web-01] /var/www/shop/releases/2026.10.23-1412.587/.env.local --> /var/www/shop/shared/.env.local
 [web-02] /var/www/shop/releases/2026.10.23-1412.587/.env.local --> /var/www/shop/shared/.env.local

 On deploy
 ---------
 composer install --no-dev --optimize-autoloader

 Publish new release
 -------------------
 [web-01] /var/www/shop/current --> /var/www/shop/releases/2026.10.23-1412.587
 [web-02] /var/www/shop/current --> /var/www/shop/releases/2026.10.23-1412.587

 Post deploy
 -----------
 php bin/console doctrine:migrations:migrate -n

 Clear olds releases
 -------------------

 [OK] All is OK

On each server, Automate maintains this layout under the configured path:

/var/www/shop
├── current -> releases/2026.10.23-1412.587
├── releases
│   ├── 2026.10.22-1805.341
│   └── 2026.10.23-1412.587
└── shared
    ├── .env.local
    └── var/uploads

The Deployment lifecycle page details every step.

Requirements

On your machine (or your CI runner):

• Linux x86_64 or macOS Apple Silicon for the prebuilt binary, or PHP 8.4+ for the PHAR. See Installation.
• tar, when you use upload actions.

On each server:

• SSH access with a password or a private key, for the default ssh transport.
• A POSIX shell and the usual tools: sh, tar, find, ln, mkdir.
• git, when you deploy from a repository. The server must be able to reach the repository, for example with a deploy key.
• Whatever your hooks need: composer, php, node, and so on.

Next steps

1. Install Automate
2. Follow the quick start to deploy your first project
3. Browse the configuration reference

1. Prepare the server

Automate needs an SSH user on the server, a directory this user can write to, and access to your Git repository from the server.

# on the server
sudo adduser deploy
sudo mkdir -p /var/www/shop
sudo chown deploy:deploy /var/www/shop

Then make sure that git is installed and that the deploy user can clone your repository, for example by adding its public key as a deploy key on GitHub or GitLab:

# on the server, as the deploy user
ssh-keygen -t ed25519 -C "deploy@web-01"
cat ~/.ssh/id_ed25519.pub   # add this key to the repository
git ls-remote git@github.com:acme/shop.git

2. Write the configuration

Create a .automate.yml file at the root of your project:

repository: git@github.com:acme/shop.git

platforms:
    production:
        default_branch: main
        servers:
            web-01:
                host: web-01.acme.io
                user: deploy
                password: "%prod_password%"
                path: /var/www/shop

shared_files:
    - .env.local

shared_folders:
    - var/uploads

on_deploy:
    - composer install --no-dev --optimize-autoloader

post_deploy:
    - php bin/console doctrine:migrations:migrate -n

A few things to note:

• production is a platform: a named group of servers deployed together. main is deployed when you do not specify another branch, tag or commit.
• "%prod_password%" is a variable. Automate reads it from the AUTOMATE__prod_password environment variable, and prompts for it in your terminal when it is not set. To authenticate with a key instead, replace password with ssh_key: /home/me/.ssh/id_ed25519.
• shared_files and shared_folders are kept between releases: the first deployment moves them to the shared folder, and every release links to them.
• on_deploy runs in the new release before it is published, post_deploy after. The hooks page lists all of them.

3. Check the connection

automate check production

Automate connects to every server of the platform and verifies that the repository is reachable from there with git ls-remote. Fix any error before deploying.

4. Deploy

automate deploy production

The first deployment creates the releases, shared and current entries under /var/www/shop. On the first deployment the hooks of on_first_deploy also run, which is a good place to create .env.local in the shared folder.

Point your web server at the current link, for example /var/www/shop/current/public for a Symfony or Laravel application. That path never changes: every deployment only updates the link.

5. Deploy something else

Deploy a branch, a tag or a commit by giving it after the platform name:

automate deploy production v1.4.0
automate deploy production hotfix/payment
automate deploy production 3f2a9c1

Where to go next

• Deployment lifecycle: what happens on the server, step by step.
• Deployment strategies: clone on the server, upload a CI build, or both.
• CI integration: run Automate from GitHub Actions or GitLab CI.
• Configuration reference: every option of .automate.yml.

Serving the current release with nginx or Caddy

Point the document root at <path>/current/public, and make the web server resolve the symbolic link before passing the script path to PHP-FPM. PHP OPcache caches scripts by path: with the resolved path, each release gets fresh entries and there is nothing to reload after a deployment. Without it, OPcache keeps serving the previous release until PHP-FPM restarts.

With nginx, use $realpath_root instead of $document_root:

server {
    server_name www.acme.io;
    root /var/www/shop/current/public;

    location / {
        try_files $uri /index.php$is_args$args;
    }

    location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/run/php/php8.4-fpm.sock;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        internal;
    }
}

Caddy resolves the link by default in php_fastcgi (resolve_root_symlink is enabled unless you turn it off):

www.acme.io {
    root * /var/www/shop/current/public
    php_fastcgi unix//run/php/php8.4-fpm.sock
    file_server
}

Symfony

repository: git@github.com:acme/shop.git

platforms:
    production:
        default_branch: main
        servers:
            web-01:
                host: web-01.acme.io
                user: deploy
                ssh_key: /home/me/.ssh/id_ed25519
                path: /var/www/shop

shared_files:
    - .env.local

shared_folders:
    - var/log
    - public/uploads

on_first_deploy:
    - 'cp .env "$AUTOMATE_SHARED_PATH/.env.local"'

on_deploy:
    - composer install --no-dev --optimize-autoloader --no-interaction
    - php bin/console cache:clear --no-warmup
    - php bin/console cache:warmup
    - php bin/console asset-map:compile

post_deploy:
    - cmd: php bin/console doctrine:migrations:migrate --no-interaction --allow-no-migration
      only: [web-01]

Point the web server at /var/www/shop/current/public as shown above. var/cache stays inside each release, which is what Symfony expects: a release always starts with a cache built for its own code.

Laravel

repository: git@github.com:acme/app.git

platforms:
    production:
        default_branch: main
        servers:
            web-01:
                host: web-01.acme.io
                user: deploy
                ssh_key: /home/me/.ssh/id_ed25519
                path: /var/www/app

shared_files:
    - .env

shared_folders:
    - storage

on_first_deploy:
    - 'cp .env.example "$AUTOMATE_SHARED_PATH/.env"'
    - php artisan key:generate --force

on_deploy:
    - composer install --no-dev --optimize-autoloader --no-interaction
    - php artisan config:cache
    - php artisan route:cache
    - php artisan view:cache

post_deploy:
    - cmd: php artisan migrate --force
      only: [web-01]
    - php artisan queue:restart

The web server serves /var/www/app/current/public. The storage folder is shared, so logs, sessions and uploads survive deployments. php artisan storage:link can be added to on_deploy when you use the public disk.

Static site built in CI

The servers only receive files. Build in the pipeline, then upload the output:

platforms:
    production:
        default_branch: main
        servers:
            web-01:
                host: web-01.acme.io
                user: deploy
                password: "%prod_password%"
                path: /var/www/site

pre_deploy:
    - upload: dist

Serve /var/www/site/current/dist. Since there is no repository, nothing needs to be installed on the server, not even git.

Assets built in CI, PHP built on the server

The mixed strategy: the server clones and installs the PHP dependencies, the CI uploads the compiled assets so that the server does not need Node.

repository: git@github.com:acme/shop.git

platforms:
    production:
        default_branch: main
        servers:
            web-01: { host: web-01.acme.io, user: deploy, ssh_key: /tmp/deploy_key, path: /var/www/shop }

shared_files: [.env.local]
shared_folders: [var/log, public/uploads]

pre_deploy:
    - upload: public/build

on_deploy:
    - composer install --no-dev --optimize-autoloader --no-interaction

post_deploy:
    - php bin/console doctrine:migrations:migrate -n

Docker Compose on the host

Deploy the sources, then rebuild and restart the containers from the published release. The local transport runs everything on the machine itself, which suits a runner installed on the host.

repository: git@github.com:acme/stack.git

platforms:
    production:
        default_branch: main
        max_releases: 2
        servers:
            host:
                transport: local
                path: /srv/stack

shared_files:
    - .env

post_deploy:
    - docker compose -f "$AUTOMATE_CURRENT_PATH/compose.yaml" up -d --build --remove-orphans

on_remove:
    - docker compose down --volumes

on_remove stops the stack before automate remove deletes the files.

Several servers behind a load balancer

Run the build everywhere, the migration once, and restart each server:

repository: git@github.com:acme/shop.git

platforms:
    production:
        default_branch: main
        servers:
            web-01: { host: web-01.acme.io, user: deploy, ssh_key: /home/me/.ssh/id_ed25519, path: /var/www/shop }
            web-02: { host: web-02.acme.io, user: deploy, ssh_key: /home/me/.ssh/id_ed25519, path: /var/www/shop }
            web-03: { host: web-03.acme.io, user: deploy, ssh_key: /home/me/.ssh/id_ed25519, path: /var/www/shop }

shared_files: [.env.local]
shared_folders: [var/log]

on_deploy:
    - composer install --no-dev --optimize-autoloader --no-interaction
    - php bin/console cache:warmup

post_deploy:
    - cmd: php bin/console doctrine:migrations:migrate -n
      only: web-01

Uploads shared by all servers, such as user files, belong on a network mount declared with shared_path:

            web-01:
                host: web-01.acme.io
                user: deploy
                ssh_key: /home/me/.ssh/id_ed25519
                path: /var/www/shop
                shared_path: /mnt/nfs/shop/shared

Staging and production in one file

repository: git@github.com:acme/shop.git

platforms:
    staging:
        default_branch: develop
        max_releases: 2
        servers:
            staging-01: { host: staging.acme.io, user: deploy, ssh_key: /home/me/.ssh/id_ed25519, path: /var/www/shop }
    production:
        default_branch: main
        max_releases: 5
        servers:
            web-01: { host: web-01.acme.io, user: deploy, ssh_key: /home/me/.ssh/id_ed25519, path: /var/www/shop }

shared_files: [.env.local]

on_deploy:
    - composer install --no-dev --optimize-autoloader --no-interaction

post_deploy:
    - php bin/console doctrine:migrations:migrate -n
    - cmd: php bin/console doctrine:fixtures:load -n --group=demo
      only: staging-01

automate deploy staging              # deploys "develop"
automate deploy production v2.3.0    # deploys a tag

Automate prints every command it runs on the servers, and the output of each one prefixed with the server name in brackets. When a step fails, the error message of the failing server is shown and the deployment stops. Add -v for more details, including the stack trace of an internal error.

To reproduce a command exactly as a hook runs it, use automate exec --current: it runs in the published release with the same environment variables.

Errors

A deployment, a removal or a rollback is already in progress

An automate.lock file exists in the project path of a server. Either another command is really running, or a previous one crashed before releasing the lock (lost connection, killed process).

When you are sure nothing is running, deploy with --force or remove the lock:

automate deploy production --force
# or
automate exec production web-01 "rm /var/www/shop/automate.lock"

Invalid user or password

The SSH authentication failed. Check the user, the password or the ssh_key of the server, and that the key is accepted by the server (~/.ssh/authorized_keys). When the key is encrypted, its passphrase goes in password.

Note that Automate reads the key file itself: the SSH agent and ~/.ssh/config are not consulted. Give the absolute path of the key.

File "..." not found

The ssh_key path does not exist on the machine that runs Automate. In CI, make sure the step that writes the key from a secret ran before the deployment, and that both use the same path.

Unable to resolve the variable "%name%"

A %name% token is used in the configuration but has no value. Provide it with --var name=value or with the AUTOMATE__name environment variable. If the % characters are not a variable, for example in date +%Y%m%d, double them: date +%%Y%%m%%d. See Variables.

Missing configuration file

No .automate.yml in the current directory. Run Automate from the root of the project, or give the file with -c path/to/.automate.yml.

Missing platform ... or Missing server ...

The name given to the command does not match a key of platforms or servers. Names are case sensitive.

Unrecognized option "..." under "automate"

A typo in a configuration key. The message lists the valid options at that level. See the Configuration reference.

The "host" option is required with the "ssh" transport

A server of the default ssh transport is missing host or user. Conversely, host, user, password and ssh_key are rejected with transport: local.

"..." does not exist

The path of an upload action does not exist on the machine that runs Automate. Paths are relative to the current directory. In CI, make sure the build step that produces the folder ran first.

Invalid "exclude" pattern

An exclude entry looks like a regular expression but is not valid. The usual cause is an unescaped delimiter: write '/^folder\/subfolder/', not '/^folder/subfolder/'. See Upload actions.

git clone or git checkout fails

The server cannot reach the repository, or the reference does not exist. Run automate check <platform> to verify the access from each server, and make sure the branch, tag or commit given to deploy exists in the repository. Private repositories need a deploy key on the server.

A hook fails with "The command failed with exit code ..."

The command exited with a non-zero status without printing anything. Run it with automate exec <platform> <server> "<command>" --current to see its full output, or add set -x at the beginning of your script.

Inspecting a failed release

When a deployment fails before publishing, its release is moved to releases/failed on each server. The release left by automate rollback goes there too. The folder is kept until the next deployment, so you can look at it:

automate exec production web-01 "ls -la /var/www/shop/releases/failed"
automate exec production web-01 "cat /var/www/shop/releases/failed/var/log/prod.log"

The application still shows the previous version

• The web server must serve <path>/current/..., not a specific release folder. Check the document root.
• PHP OPcache caches scripts by their resolved path. When the web server passes /var/www/shop/current/public/index.php to PHP-FPM, OPcache keeps serving the file it resolved at the first request, which may belong to the previous release. Configure the web server to resolve the current link itself, so that every release has its own paths: see Serving the current release.
• Long-running processes (queue workers, Node servers) keep the old release until they restart: restart them in post_deploy.

Rolling back

Run automate rollback <platform> to point current back to the previous release on every server, or give it a release id. See Deployment lifecycle.

Windows

The install script and the static binaries target Linux and macOS. On Windows, run the PHAR with PHP 8.4+. The local transport is not available there; deploying to remote servers over SSH works.

Getting help

• Browse the existing issues, or open a new one with your configuration (without secrets) and the output of the failing command.
• Pull requests are welcome: see the repository.

platforms:
    review:
        default_branch: main
        servers:
            vm:
                host: review.acme.io
                user: deploy
                password: "%review_password%"
                path: /srv/review/%slug%

post_deploy:
    - bash deploy/notify.sh   # reads $AUTOMATE__slug and $AUTOMATE_RELEASE_PATH

Resolution order

Values are looked up in this order:

1. the --var name=value option of deploy, rollback, check, remove and exec, which can be repeated: automate deploy review my-branch --var slug=my-branch
2. the environment variable AUTOMATE__name, for example AUTOMATE__review_password;
3. for a password only, an interactive prompt in the terminal.

A variable that cannot be resolved stops the command with an error naming the configuration key and the ways to provide the value. Only the platform being deployed is resolved: the variables of the other platforms are not needed.

Passwords: the prompt is only offered when the whole password value is a token, such as "%prod_password%". Any other password is used as is. A name used as a password is accepted in any case, such as %PROD_PASSWORD%, for compatibility with older configurations.

In CI pipelines

Pipelines have no terminal, so passwords must come from the environment or from --var. Map your CI secrets to AUTOMATE__* variables:

# GitHub Actions
env:
    AUTOMATE__prod_password: ${{ secrets.PROD_PASSWORD }}

See CI integration for complete examples.

Masking

The deploy summary lists the names of the variables, never their values. In the commands printed to the console, each value is replaced by its %name% token. The values are still exported to the hooks as AUTOMATE__name environment variables, except the ones used as a password.

Escaping and quoting

• Write %% to get a literal %. Commands that contain a valid token are the usual trap: in date +%Y%m%d, %m% is a token, and in printf '%s%s', %s% is a token. Write date +%%Y%%m%%d and printf '%%s%%s'.
• Quote a YAML value that starts with %: password: "%prod_password%".
• Values are inserted as is, without shell escaping. Use trusted values, or reference the variable through the environment in a command: "$AUTOMATE__slug".
• --var does not accept an empty value.