# Deployment Hooks

# Overview

Deployment hooks allow you to customize your entire deployment plan by writing small Bash scripts to automate parts of your deployment. You may also specify the servers on which each hook is executed and the user that runs the hook.

Envoyer creates either three or four actions that cannot be modified or re-ordered:

  • Clone New Release
  • Install Composer Dependencies (if you have configured your project to do so)
  • Activate New Release
  • Purge Old Releases

Your custom hooks can be moved around before/after each of these fixed actions.

Like any other step during your deployment, if a deployment hook exits with a non-zero status code, the entire deployment will be cancelled. This prevents your applications from experiencing downtime with a broken deployment.

# Push To Deploy URL

If you need to trigger deployments as part of your CI or other process, instead of when a branch is pushed to, you can choose to use the "Push To Deploy" URL that is generated by Envoyer for your project.

Refresh The URL

You may regenerate the "Push To Deploy" URL at any time by clicking the refresh icon next to the URL within the Deployment Hooks tab of your project.

# Deployment Options

You can pass either a sha or branch parameter to the deployment URL to choose what to deploy.

# Deployment Lifecycle

When a deployment is triggered for your project, Envoyer will execute your deployment plan. By default, this consists of downloading a tarball of your project, installing the Composer dependencies (if configured), pointing the current symbolic link at the latest release, and finally purging any old deployments from your server.

Of course, any deployment hooks you have configured will also be run during the deployment in their configured sequence.

# Hook Variables

Within your deployment hook script, you may use the release variable to access the most current release directory. For example:

cd {{ release }}

php artisan command

The available variables are:

Name Description
author Resolves to the author of the commit that is being deployed
branch Resolves to the branch that Envoyer is configured to deploy
project Resolves to the project's root directory (the directory which contains current, releases and storage)
release Resolves to the current release path, within releases
sha Resolves to the commit hash that is being deployed
time Resolves to the current deployment formatted as YmdHis
php Resolves to the server's configured PHP path
composer Resolves to the server's configured Composer path

Variable Formatting

Variables can be written with or without a space inside of the braces, i.e. {{ variable }} is the same as {{variable}}