Introduction
Laravel Envoy provides a clean, minimal syntax for defining common tasks you run on your remote servers. Using Blade style syntax, you can easily setup tasks for deployment, Artisan commands, and more. Currently, Envoy only supports the Mac and Linux operating systems.
Installation
First, install Envoy using the Composer global require command:
composer global require laravel/envoy
Since global Composer libraries can sometimes cause package version conflicts, you may wish to consider using cgr, which is a drop-in replacement for the composer global require command. The cgr library’s installation instructions can be found on GitHub.
Updating Envoy
You may also use Composer to keep your Envoy installation up to date. Issuing the composer global update command will update all of your globally installed Composer packages:
composer global update
Writing Tasks
All of your Envoy tasks should be defined in an Envoy.blade.php file in the root of your project. Here’s an example to get you started:
@servers([‘web’ => [‘user@192.168.1.1’]])
@task(‘foo’, [‘on’ => ‘web’])
ls -la
@endtask
As you can see, an array of @servers is defined at the top of the file, allowing you to reference these servers in the on option of your task declarations. Within your @task declarations, you should place the Bash code that should run on your server when the task is executed.
You can force a script to run locally by specifying the server’s IP address as 127.0.0.1:
@servers([‘localhost’ => ‘127.0.0.1’])
Setup
Sometimes, you may need to execute some PHP code before executing your Envoy tasks. You may use the @setup directive to declare variables and do other general PHP work before any of your other tasks are executed:
Variables
If needed, you may pass option values into Envoy tasks using the command line:
envoy run deploy –branch=master
You may access the options in your tasks via Blade’s “echo” syntax. Of course, you may also use if statements and loops within your tasks. For example, let’s verify the presence of the $branch variable before executing the git pull command:
@servers([‘web’ => ‘192.168.1.1’])
@task(‘deploy’, [‘on’ => ‘web’])
cd site
@if ($branch)
git pull origin {{ $branch }}
@endif
php artisan migrate
@endtask
Notifications
Slack
Envoy also supports sending notifications to Slack after each task is executed. The @slack directive accepts a Slack hook URL and a channel name. You may retrieve your webhook URL by creating an “Incoming WebHooks” integration in your Slack control panel. You should pass the entire webhook URL into the @slack directive:
@finished
@slack(‘webhook-url’, ‘#bots’)
@endfinished
You may provide one of the following as the channel argument:
To send the notification to a channel: #channel
To send the notification to a user: @user
