Envoy compatibility

Scotty can read existing Laravel 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.

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 work here:

@option('staging')
@option('branch=main')
@option('tag=')

Form	Behaviour
@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.