With Laravel Envoy, how do @servers, @task and @story describe a deploy, and what happens when one command in a task fails?

## What Envoy is Laravel Envoy is a small tool for running shell tasks on remote servers over SSH, written with Blade-style syntax. It is installed per project as a dev dependency: ```bash composer require laravel/envoy --dev php vendor/bin/envoy run deploy ``` It runs on Mac and Linux; Windows needs WSL2. Tasks live in `Envoy.blade.php` at the project root. ## The building blocks | Directive | Purpose | |---|---| | `@servers([...])` | names the hosts; must be written on a single line | | `@task('name', [...])` ... `@endtask` | shell commands to run on the servers in `on` | | `@story('name')` ... `@endstory` | a list of task names run in order | | `@setup` ... `@endsetup` | PHP run locally before tasks, for variables | | `@import('path')` | pulls in another Envoy file's tasks and stories | | `@before`, `@after`, `@error`, `@success`, `@finished` | PHP hooks run **locally** around tasks | Task options worth knowing: - `on` — one server name or an array of them; - `parallel` — `true` runs the task on all its servers at once instead of one after another; - `confirm` — `true` asks for confirmation before running, useful for destructive tasks. Command-line options become Blade variables: `vendor/bin/envoy run deploy --branch=main` makes `{{ $branch }}` available inside tasks, and `@if ($branch)` works too. ## A deploy for the ticketing platform ```html @servers(['web-1' => '[email protected]', 'web-2' => '[email protected]']) @story('deploy') install migrate finish @endstory @task('install', ['on' => ['web-1', 'web-2'], 'parallel' => true]) cd /var/www/tickets git pull origin {{ $branch }} composer install --no-dev --no-interaction @endtask @task('migrate', ['on' => 'web-1']) cd /var/www/tickets php artisan migrate --force @endtask @task('finish', ['on' => ['web-1', 'web-2']]) cd /var/www/tickets php artisan optimize php artisan reload @endtask ``` Migrations run on one server only; the other steps run on every web server. ## What happens on failure Envoy sends each task's script to the server as `ssh <host> 'bash -se' << EOF` with `set -e` at the top. Two consequences follow: 1. **Inside a task,** the first command that exits non-zero ends the task on that server; later lines do not run. 2. **Across a story,** `envoy run` stops at the first task that returns a non-zero code and prints "This task did not complete successfully on one of your servers." Remaining tasks do not run unless you pass `--continue`. Afterwards the hooks fire: `@error` after a failed task, `@success` only when everything succeeded, `@finished` always, with the exit code. They run on the machine that invoked Envoy, which is where notification directives such as `@slack` belong. ## Useful options - `--pretend` prints the generated Bash script instead of running it, a quick way to check a story. - `--path` and `--conf` point Envoy at a different file. ## Common mistakes - Splitting `@servers` over several lines; the docs require a single line. - Running migrations in a task that targets every server, so they race each other. - Expecting hooks to run remotely; they run in the local PHP process. - Forgetting that each task starts in a fresh shell, so every task needs its own `cd` into the application directory. ## Where Envoy fits Envoy is a thin runner: it does not provide release directories, rollbacks or health checks by itself. Those come from how you write the tasks.