Envoy compatibility | scotty | Spatie SPATIE Scotty ========= spatie.be/open-source [Docs](https://spatie.be/docs) [Scotty](https://spatie.be/docs/scotty/v1) Advanced-usage Envoy compatibility Version v1 Other versions for crawler [v1](https://spatie.be/docs/scotty/v1) Envoy compatibility - [ Introduction ](https://spatie.be/docs/scotty/v1/introduction) - [ Support us ](https://spatie.be/docs/scotty/v1/support-us) - [ Getting started ](https://spatie.be/docs/scotty/v1/getting-started) - [ Requirements ](https://spatie.be/docs/scotty/v1/requirements) - [ Installation & setup ](https://spatie.be/docs/scotty/v1/installation) - [ Questions and issues ](https://spatie.be/docs/scotty/v1/questions-issues) - [ Changelog ](https://spatie.be/docs/scotty/v1/changelog) - [ About us ](https://spatie.be/docs/scotty/v1/about-us) Basic Usage ----------- - [ Your first deploy script ](https://spatie.be/docs/scotty/v1/basic-usage/your-first-deploy-script) - [ The Scotty.sh format ](https://spatie.be/docs/scotty/v1/basic-usage/bash-format) - [ Running tasks ](https://spatie.be/docs/scotty/v1/basic-usage/running-tasks) Advanced Usage -------------- - [ Doctor ](https://spatie.be/docs/scotty/v1/advanced-usage/doctor) - [ File lookup order ](https://spatie.be/docs/scotty/v1/advanced-usage/file-lookup-order) - [ Envoy compatibility ](https://spatie.be/docs/scotty/v1/advanced-usage/envoy-compatibility) - [ Zero-downtime deployments ](https://spatie.be/docs/scotty/v1/advanced-usage/zero-downtime-deployments) Envoy compatibility =================== ### On this page 1. [ Defining servers ](#content-defining-servers) 2. [ Defining tasks ](#content-defining-tasks) 3. [ Setup ](#content-setup) 4. [ Variables ](#content-variables) 5. [ Stories (macros) ](#content-stories-macros) 6. [ Hooks ](#content-hooks) 7. [ Importing tasks ](#content-importing-tasks) Scotty can read existing [Laravel Envoy](https://laravel.com/docs/envoy) files out of the box. If your project has an `Envoy.blade.php`, you can run it with Scotty without changing anything. Just run `scotty run deploy` (or whatever your task is called) and it works. This page documents the Blade file format that Envoy uses, so you can understand your existing file before deciding whether to [migrate to the Scotty.sh format](/docs/scotty/v1/basic-usage/bash-format#migrating-from-envoy). All tasks should be defined in an `Envoy.blade.php` file at the root of your project. Defining servers -------------------------------------------------------------------------------------------------------- Define your servers with the `@servers` directive at the top of the file: ``` @servers(['web' => ['user@192.168.1.1'], 'workers' => ['user@192.168.1.2']]) ``` The `@servers` declaration should always be placed on a single line. Defining tasks -------------------------------------------------------------------------------------------------- Tasks are the basic building block. They contain the shell commands that should execute on your remote servers: ``` @servers(['web' => ['user@192.168.1.1']]) @task('deploy', ['on' => 'web']) cd /home/user/example.com git pull origin main php artisan migrate --force @endtask ``` ### Local tasks To run a script on your local machine, use `127.0.0.1` as the server address: ``` @servers(['localhost' => '127.0.0.1']) ``` ### Multiple servers List multiple servers in the `on` array to run a task on each one: ``` @servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2']) @task('deploy', ['on' => ['web-1', 'web-2']]) cd /home/user/example.com git pull origin {{ $branch }} php artisan migrate --force @endtask ``` By default, the task finishes on the first server before starting on the second. ### Parallel execution To run on all servers at the same time, add the `parallel` option: ``` @task('deploy', ['on' => ['web-1', 'web-2'], 'parallel' => true]) cd /home/user/example.com git pull origin {{ $branch }} @endtask ``` ### Task confirmation Add `confirm` to prompt before running: ``` @task('deploy', ['on' => 'web', 'confirm' => true]) cd /home/user/example.com git pull origin main @endtask ``` Setup ----------------------------------------------------------------------- If you need to execute PHP code before your tasks run, use the `@setup` directive: ``` @setup $now = new DateTime; $branch = 'main'; $releaseName = $now->format('YmdHis'); @endsetup ``` To require other PHP files, use `@include` at the top of your file: ``` @include('vendor/autoload.php') ``` Variables ----------------------------------------------------------------------------------- Declare CLI options with `@option` at the top of your file. The same three forms supported in the [Scotty.sh format](/docs/scotty/v1/basic-usage/running-tasks#dynamic-options) work here: ``` @option('staging') @option('branch=main') @option('tag=') ``` FormBehaviour`@option('staging')`Boolean flag. `$staging` is `'1'` when `--staging` is passed, otherwise `null`.`@option('branch=main')`Optional value with a default. Uses `--branch=...`, the `BRANCH` env var, then `'main'`.`@option('tag=')`Required value. Errors if `--tag=...` is not provided.Pass values from the command line: ``` scotty run deploy --branch=develop ``` Access them in tasks using Blade's echo syntax: ``` @task('deploy', ['on' => 'web']) cd /home/user/example.com @if ($branch) git pull origin {{ $branch }} @endif php artisan migrate --force @endtask ``` Dashed names like `@option('release-name')` are exposed as both `$release_name` and `$releaseName`. Undeclared flags (e.g. `--branch=develop` without a matching `@option('branch=...')`) are rejected by the CLI. Stories (macros) ---------------------------------------------------------------------------------------------------- Stories group tasks under a single name: ``` @servers(['web' => ['user@192.168.1.1']]) @story('deploy') update-code install-dependencies @endstory @task('update-code') cd /home/user/example.com git pull origin main @endtask @task('install-dependencies') cd /home/user/example.com composer install @endtask ``` Run a story the same way you run a task: ``` scotty run deploy ``` Hooks ----------------------------------------------------------------------- Hooks run at different points during execution. All hook code is interpreted as PHP and executed locally. ### @before Runs before each task: ``` @before if ($task === 'deploy') { // ... } @endbefore ``` ### @after Runs after each task: ``` @after if ($task === 'deploy') { // ... } @endafter ``` ### @error Runs when a task fails (exit code greater than 0): ``` @error if ($task === 'deploy') { // ... } @enderror ``` ### @success Runs if all tasks executed without errors: ``` @success // ... @endsuccess ``` ### @finished Runs after all tasks, regardless of the outcome: ``` @finished if ($exitCode > 0) { // ... } @endfinished ``` Importing tasks ----------------------------------------------------------------------------------------------------- You can import other Envoy files: ``` @import('vendor/package/Envoy.blade.php') ``` For the full Blade format reference, see the [Laravel Envoy documentation](https://laravel.com/docs/envoy). A good match? ------------- ### What we do best - All things Laravel - Custom frontend components - Building APIs - AI-powered features - Simplifying things - Clean solutions - Integrating services ### Not our cup of tea - WordPress themes - Cutting corners - Free mockups to win a job - "Just execute the briefing" In short: we'd like to be a **substantial part** of your project. [ Get in touch via email ](mailto:info@spatie.be?subject=A%20good%20match%21&body=Tell%20us%20as%20much%20as%20you%20can%20about%0A-%20your%20online%20project%0A-%20your%20planning%0A-%20your%20budget%0A-%20%E2%80%A6%0A%0AAnything%20that%20helps%20us%20to%20start%20straightforward%21)