Deployment Hooks
Learn how to deploy your projects with 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 several first-party deployment hooks 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 re-ordered 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 application from experiencing downtime due to a broken deployment.
Push To Deploy URL
If you need to trigger deployments as part of your CI or other automated process instead of when code is pushed to your repository, you can choose to use the “Push To Deploy” URL that is generated by Envoyer for your project. To trigger a deployment using this URL, simply make an HTTP GET or POST request to 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 URL Options
You may pass either a sha or branch parameter to the deployment URL to choose which branch or Git commit to deploy. These parameters may be passed as query string variables or POST fields.
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 scripts, you may use the release variable to access the most current release directory. For example:
Other available variables are:
| Name | Description |
|---|---|
author | The author of the commit that is being deployed |
branch | The branch that Envoyer is configured to deploy |
message | The message of the commit that is being deployed |
project | The project’s root directory (the directory which contains current, releases and storage) |
release | The current release path, within releases |
sha | The commit hash that is being deployed |
time | The current deployment formatted as YmdHis |
php | The server’s configured PHP path |
composer | The server’s configured Composer path |
name | The project’s name |
Variables can be written with or without a space inside of the curly braces. For example, {{ variable }} is the same as {{variable}}