Elegant SSH tasks for PHP.

• Installation
• Running Tasks
• Passing Variables
• Macros
• Multiple Servers
• Parallel Execution
• HipChat Notifications
• Slack Notifications

Envoy is a simple SSH task runner for PHP 5.4 or greater. It is loosely inspired by Python Fabric. It supports:

• Clean, minimal syntax for defining tasks.
• Utilizes ~/.ssh/config settings.
• Parallel execution across multiple servers.
• Stops execution if any command fails.
• Macros quickly group tasks into a single command.
• HipChat notifications.

Envoy is perfect for automating common tasks you perform on your remote servers such as deployment, restarting queues, etc.

The simplest method of installation is to install it as a global Composer package:

composer global require "laravel/envoy=~1.0"

Once the package has been installed, you should add the global Composer bin directory to your PATH. On Mac / Linux systems, this directory is ~/.composer/vendor/bin.

To update Envoy, you may use the composer global update command.

Create an Envoy.blade.php file in any directory. Here is a sample file to get you started:

@servers(['web' => '[email protected]'])

@task('foo', ['on' => 'web'])
	ls -la
@endtask

You may also use the init command to create a stub Envoy file. For example:

envoy init [email protected]

You may define multiple tasks in a given file. To run a task, use the run command:

envoy run foo

Note: For best results, your machine should have SSH key access to the target.

envoy run foo --branch=master

@task('foo')
	cd site
	git pull origin {{ $branch }}
	php artisan migrate
@endtask

Macros allow you to define a set of tasks to run in sequence using a single command. For instance:

@macro('deploy')
	foo
	bar
@endmacro

@task('foo')
	echo "HELLO"
@endtask

@task('bar')
	echo "WORLD"
@endtask

envoy run deploy

@servers(['web' => '[email protected]', 'db' => '[email protected]'])

@task('foo', ['on' => ['web', 'db']])
	ls -la
@endtask

Note: Tasks on multiple servers will be run serially by default.

To run a task across multiple servers in parallel, use the parallel option on the task:

@servers(['web' => '[email protected]', 'db' => '[email protected]'])

@task('foo', ['on' => ['web', 'db'], 'parallel' => true])
	ls -la
@endtask

@servers(['web' => '192.168.1.1'])

@task('foo', ['on' => 'web'])
	ls -la
@endtask

@after
	@hipchat('token', 'room', 'from')
@endafter

Note: HipChat notifications will only be sent if all tasks complete successfully.

@servers(['web' => '192.168.1.1'])

@task('foo', ['on' => 'web'])
	ls -la
@endtask

@after
	@slack('team', 'token', 'channel')
@endafter

You may retrieve your token by creating an Incoming WebHooks integration on Slack's website.

The team argument is your Slack subdomain (fooapp.slack.com = fooapp).

You may provide one of the following for the channel argument:

• For a regular channel: #channel
• For a specific user: @user
• For a private group: group
• If no argument is provided Envoy will use the default channel configured on the Slack website.

Note: Slack notifications will only be sent if all tasks complete successfully.