This add-on does virtually nothing on its own. The point is to put a few tools in place with which a developer can more easily utilize software web hooks to automatically execute actions before and after site deployments.

This is achieved by creating two action URLs in EE (yoursite.com/?ACT=xx) and running security checks before executing any sensitive code. These URLs call two hooks in the add-on which trigger any extensions you will have installed for this add-on. I imagine most users will write their own extension(s) within the context of their own add-on.

Deployment Hooks requires ExpressionEngine 2.1.3 or greater

• Move the deployment_hooks folder into your expressionengine/third_party folder
• Go to Modules → Deployment Hooks → Install

Optionally install the Beanstalk Toggle System add-on included in the package for a sample use of Deployment Hooks

• Move the beanstalk_toggle_system_ folder into your expressionengine/third_party folder
• Go to Admin → Utilities → Extensions and install Beanstalk Toggle System

• Adds 2 unique URLs to your site for Pre and Post deployment actions
• Hooks are secured by GET key/value tokens and/or IP-based restriction
• Each deployment hook use is logged in the database (upon success OR failure)
• Easily see what extensions use the Deployment Hooks module
• Easily check the recent log notes via an Accessory (if desired)

In an effort to keep the average user from simply browsing to your Deployment Hooks URL, you can optionally configure two security-based settings for the add-on.

Enter a key/value pair in the forms of a URL Get variable to prevent your URLs from being accessed without the token. A sample would be something like answer2life=42 which would turn your Deployment Hook URL into something like http://yoursite.com/?ACT=35&answer2life=42.

If you use this setting and the key/value is missing from the URL then the code does not get executed any further.

You can optionally enter a pipe-delimited list of IPs to create a “whitelist” of sorts for the add-on. If you enter any IPs in this list you thereby block any IPs not in the list.

This would be used to limit the Deployment Hooks execution to your deployment server IP (or range of IPs). An example would be including the IPs from Beanstalk in their documentation here: http://help.beanstalkapp.com/kb/security-backups/ports-and-ip-addresses

Setting up Deployment Hooks is as simple as copying and pasting the pre and post deployment hook URLs into the right place. We use Beanstalk to deploy our sites so you can see an example of where you’d use the URLs in the following way:

1. Select a repository
2. Go to the Deployments tab
3. Add or Edit a server environment
4. Paste your Deployment Hooks URLs into the related fields

After setting up your hook URLs, ensure that your custom extension(s) are installed and ready to roll.

A sample extension is included in the download of Deployment Hooks. In this extension you can see how it utilizes each hook (both pre and post) to turn the EE system off before the deployment begins, then back on when the deployment is completed.

The extension is built to use Beanstalk specifically so we know what data format to expect as an input. Because of this we can use some extra security to check and make sure the request is originating from the right place. Review this extension to get an idea of how you can utilize these hooks.

It’s certainly possible (and tested) to use multiple extensions with this add-on.

The most important part of using this add-on is ensuring that you utilize the Deployment Hooks log. To do this you simply return an array at the end of your method. The array should simply contain strings for each action.

As a reference point it may also be good to include your extension’s name in the log item. This way if Deployment Hooks is using multiple extensions it will be clear which one logged which action. Here is a sample from the log:

1. Post-Deployment Hook initiated
2. Security check passed. Continuing.
3. Beanstalk Toggle System: Successfully turned on the system after rev agd76d89
4. Post-Deployment Hook completed

Here is how the hooks appear in the code (gist):

<?php

if ($this->_EE->extensions->active_hook('deployment_hooks_'.$which.'_deploy') === TRUE)
{
    $ext_response = $this->_EE->extensions->call('deployment_hooks_'.$which.'_deploy');
    $this->response = is_array($ext_response) ? array_merge($this->response,$ext_response) : $this->response ;
}

?>

If you have any questions about implementation send an email to dev@focuslabllc.com.

This add-on was a byproduct of our team trying to make our deployment process more efficient and DRY. We would love to have community input and code contribution. Feel free to fork the repository and send pull requests.

Support for Deployment Hooks will be very limited due to its cost to you (nothing!). We ask that you file any issues in the GitHub repository under the Issues tab.

May 3rd, 2011: 1.0.0

• Initial Release