> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Envoy

> Learn how to use Laravel Envoy to define and run deployment tasks and Artisan commands on remote servers using Blade-style syntax.

## Introduction

[Laravel Envoy](https://github.com/laravel/envoy) is a tool for executing common tasks you run on your remote servers. Using [Blade](/en/blade) style syntax, you can easily set up tasks for deployment, Artisan commands, and more.

<Info>
  Currently, Envoy only supports the Mac and Linux operating systems. However, Windows support is achievable using [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install-win10).
</Info>

## Installation

First, install Envoy into your project using the Composer package manager:

```shell theme={null}
composer require laravel/envoy --dev
```

Once Envoy has been installed, the Envoy binary will be available in your application's `vendor/bin` directory:

```shell theme={null}
php vendor/bin/envoy
```

## Writing Tasks

### Defining Tasks

Tasks are the basic building block of Envoy. Tasks define the shell commands that should execute on your remote servers when the task is invoked. All of your Envoy tasks should be defined in an `Envoy.blade.php` file at the root of your application.

```blade theme={null}
@servers(['web' => ['user@192.168.1.1'], 'workers' => ['user@192.168.1.2']])

@task('restart-queues', ['on' => 'workers'])
    cd /home/user/example.com
    php artisan queue:restart
@endtask
```

As you can see, an array of `@servers` is defined at the top of the file, allowing you to reference these servers via the `on` option of your task declarations. The `@servers` declaration should always be placed on a single line.

#### Local Tasks

You can force a script to run on your local computer by specifying the server's IP address as `127.0.0.1`:

```blade theme={null}
@servers(['localhost' => '127.0.0.1'])
```

#### Importing Envoy Tasks

Using the `@import` directive, you may import other Envoy files so their stories and tasks are added to yours.

```blade theme={null}
@import('vendor/package/Envoy.blade.php')
```

### Multiple Servers

Envoy allows you to easily run a task across multiple servers. First, add additional servers to your `@servers` declaration. Once you have defined your additional servers you may list each of them in the task's `on` array:

```blade theme={null}
@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
```

#### Parallel Execution

By default, tasks will be executed on each server serially. If you would like to run a task across multiple servers in parallel, add the `parallel` option to your task declaration:

```blade theme={null}
@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])

@task('deploy', ['on' => ['web-1', 'web-2'], 'parallel' => true])
    cd /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate --force
@endtask
```

### Setup

Sometimes, you may need to execute arbitrary PHP code before running your Envoy tasks. You may use the `@setup` directive:

```php theme={null}
@setup
    $now = new DateTime;
@endsetup
```

If you need to require other PHP files before your task is executed, use the `@include` directive at the top of your `Envoy.blade.php` file:

```blade theme={null}
@include('vendor/autoload.php')

@task('restart-queues')
    # ...
@endtask
```

### Variables

If needed, you may pass arguments to Envoy tasks by specifying them on the command line when invoking Envoy:

```shell theme={null}
php vendor/bin/envoy run deploy --branch=master
```

You may access the options within your tasks using Blade's "echo" syntax and define `if` statements and loops:

```blade theme={null}
@servers(['web' => ['user@192.168.1.1']])

@task('deploy', ['on' => 'web'])
    cd /home/user/example.com

    @if ($branch)
        git pull origin {{ $branch }}
    @endif

    php artisan migrate --force
@endtask
```

### Stories

Stories group a set of tasks under a single, convenient name.

```blade theme={null}
@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 master
@endtask

@task('install-dependencies')
    cd /home/user/example.com
    composer install
@endtask
```

Once the story has been written, you may invoke it in the same way you would invoke a task:

```shell theme={null}
php vendor/bin/envoy run deploy
```

### Hooks

When tasks and stories run, a number of hooks are executed. The hook types supported by Envoy are `@before`, `@after`, `@error`, `@success`, and `@finished`. All of the code in these hooks is interpreted as PHP and executed **locally**, not on the remote servers your tasks interact with.

```blade theme={null}
@before
    if ($task === 'deploy') {
        // ...
    }
@endbefore

@after
    if ($task === 'deploy') {
        // ...
    }
@endafter

@error
    if ($task === 'deploy') {
        // ...
    }
@enderror

@success
    // ...
@endsuccess

@finished
    if ($exitCode > 0) {
        // There were errors in one of the tasks...
    }
@endfinished
```

The `@finished` hooks receive the status code of the completed task, which may be `null` or an `integer` greater than or equal to `0`.

## Running Tasks

To run a task or story that is defined in your application's `Envoy.blade.php` file, execute Envoy's `run` command:

```shell theme={null}
php vendor/bin/envoy run deploy
```

### Confirming Task Execution

If you would like to be prompted for confirmation before running a given task on your servers, add the `confirm` directive to your task declaration. This option is particularly useful for destructive operations:

```blade theme={null}
@task('deploy', ['on' => 'web', 'confirm' => true])
    cd /home/user/example.com
    git pull origin {{ $branch }}
    php artisan migrate
@endtask
```

## Notifications

### Slack

Envoy supports sending notifications to [Slack](https://slack.com) after each task is executed. The `@slack` directive accepts a Slack hook URL and a channel / user name.

```blade theme={null}
@finished
    @slack('webhook-url', '#bots')
@endfinished
```

You may overwrite the default message by passing a third argument to the `@slack` directive:

```blade theme={null}
@finished
    @slack('webhook-url', '#bots', 'Hello, Slack.')
@endfinished
```

### Discord

```blade theme={null}
@finished
    @discord('discord-webhook-url')
@endfinished
```

### Telegram

```blade theme={null}
@finished
    @telegram('bot-id','chat-id')
@endfinished
```

### Microsoft Teams

The `@teams` directive accepts a Teams webhook (required), a message, a theme color (success, info, warning, error), and an optional array of options.

```blade theme={null}
@finished
    @teams('webhook-url')
@endfinished
```

<Warning>
  Envoy relies on SSH connections to your remote servers. Make sure key-based authentication and server access are configured before running tasks. For more advanced deployment automation, consider combining Envoy with the [deployment](/en/deployment) guide or [GitHub Actions](/en/advanced/github-actions-pinning).
</Warning>