Cloud Hooks is a feature of Acquia Cloud, the Drupal cloud hosting platform. For more information, see https://www.acquia.com/products-services/acquia-dev-cloud.
The Acquia Cloud Workflow page automates the most common tasks involved in developing a Drupal site: deploying code from a version control system, and migrating code, databases, and files across your Development, Staging, and Production environments. Cloud Hooks allow you to automate other tasks as part of these migrations.
A Cloud Hook is simply a script in your code repository that Acquia Cloud executes on your behalf when a triggering action occurs. Examples of tasks that you can automate with Cloud Hooks include:
- Perform Drupal database updates each time new code is deployed.
- "Scrub" your Production database when it is copied to Dev or Staging by removing customer emails or disabling production-only modules.
- Run your test suite or a site performance test each time new code is deployed.
Cloud hook scripts live in your Acquia Cloud code repository. In each branch of your repo, there is a directory named docroot that contains your site's source code. Cloud hooks live in the directory hooks NEXT TO docroot (not inside of docroot).
To install the correct directory structure and sample hook scripts, simply copy this repo into your Acquia Cloud repo.
cd /my/repo
curl -L -o hooks.tar.gz https://github.com/acquia/cloud-hooks/tarball/master
tar xzf hooks.tar.gz
mv acquia-cloud-hooks-* hooks
git add hooks
git commit -m 'Import Cloud hooks directory and sample scripts.'
git push
To get an idea of the power of Cloud Hooks, let's run the "Hello, Cloud!" script when new code is deployed in to your Dev environment.
-
Install the hello-world.sh script to run on code deployments to Dev. This example assumes your Dev environment is running the 'master' branch.
cd /my/repo git checkout master cp hooks/samples/hello-world.sh hooks/dev/post-code-deploy git commit -a 'Run the hello-world script on post-code-deploy to Dev.' git push -
Visit the Workflow page in the Acquia Cloud UI. In the Dev environment, select the 'master' branch (if your Dev environment is already running master, select any other tag and then select master again), then press Deploy.
-
Scroll down on the Workflow page. When the code deployment task is done, click its "Show" link to see the hook's output. It will look like this:
Started Updating s1.dev to deploy master Deploying master on s1.dev [05:28:33] Starting hook: post-code-deploy Executing: /var/www/html/s1.dev/hooks/dev/post-code-deploy/hello-world.sh s1 dev master master s1@svn-3.bjaspan.hosting.acquia.com:s1.git git (as s1@srv-4) Hello, Cloud! [05:28:34] Finished hook: post-code-deploy
You can use the Code drop-down list to put your Dev environment back to whatever it was previously deploying.
The hooks directory in your repo has a directory structure like this:
/hooks / [env] / [hook] / [script]
-
[env] is a directory whose name is an environment name: 'dev' for Development, 'test' for Staging, and 'prod' for Production, as well as 'common' for all environments.
-
[hook] is a directory whose name is a Cloud Hook name: see below for supported hooks.
-
[script] is a program or shell script within the [env]/[hook] directory.
Each time a hookable action occurs, Acquia Cloud runs scripts from the directory common/[hook] and [target-env]/[hook]. All scripts in the hook directory are run, in lexicographical (shell glob) order. If one of the hook scripts exits with non-zero status, the remaining hook scripts are skipped, and the task is marked "failed" on the Workflow page so you know to check it. All stdout and stderr output from all the hooks that ran are displayed in the task log on the Workflow page.
Note that hook scripts must have the Unix "executable" bit in order to run. If your script has the execute bit set when you first add it to Git, you're all set. Otherwise, to set the execute bit to a file already in your Git repo:
chmod a+x ./my-hook.sh
git add ./my-hook.sh
git commit -m 'Add execute bit to my-hook.sh'
git push
The samples directory contains bare-bones example scripts for each of the supported hooks, plus a variety of useful user-contributed scripts. Each script starts with comments explaining what it is for and how it works.
Sample scripts currently include:
- post-code-deploy.tmpl: Template for post-code-deploy hook scripts.
- post-code-update.tmpl: Template for post-code-update hook scripts.
- post-db-copy.tmpl: Template for post-db-copy hook scripts.
- post-files-copy.tmpl: Template for post-files-copy hook scripts.
- pre-site-code-deploy.tmpl: Template for pre-site-code-deploy hook scripts.
- post-site-code-deploy.tmpl: Template for post-site-code-deploy hook scripts.
- pre-site-wipe.tmpl: Template for pre-site-wipe hook scripts.
- post-site-wipe.tmpl: Template for post-site-wipe hook scripts.
- post-site-instance-duplicate.tmpl: Template for post-site-instance-duplicate hook scripts.
- post-site-associate.tmpl: Template for post-site-associate hook scripts.
- update-db.sh: Run drush updatedb to perform database updates.
- db-scrub.sh: Scrub important information from a Drupal database.
- maintenance-mode-enable.sh: Enable Drupal maintenance mode before site deployment.
- maintenance-mode-disable-and-update.sh: Disable maintenance mode and optionally run database updates after site deployment.
- drupal-tests.sh: Run Drupal simpletests.
- rollback.sh: Run designated simpletest testing against a branch/tag and rollback on failure.
- newrelic.sh: Example of Acquia Hosting Cloud Hook to notify New Relic API of code version deployments.
This section defines the currently supported Cloud Hooks and the command-line arguments they receive.
The post-code-deploy hook is run whenever you use the Workflow page to deploy new code to an environment, either via drag-drop or by selecting an existing branch or tag from the Code drop-down list. (The post-code-update hook runs after every code commit.)
Usage: post-code-deploy site target-env source-branch deployed-tag repo-url repo-type
- site: The site name. This is the same as the Acquia Cloud username for the site.
- target-env: The environment to which code was just deployed.
- source-branch: The code branch or tag being deployed. See below.
- deployed-tag: The code branch or tag being deployed. See below.
- repo-url: The URL of your code repository.
- repo-type: The version control system your site is using; "git".
The meaning of source-branch and deployed-tag depends on whether you use drag-drop to move code from one environment to another or whether you select a new branch or tag for an environment from the Code drop-down list:
-
With drag-drop, the "source branch" is the branch or tag that the environment you dragged from is set to, and the "deployed tag" is the tag just deployed in the target environment. If source-branch is a branch (does not start with "tags/"), deployed-tag will be a newly created tag pointing at the tip of source-branch. If source-branch is a tag, deployed-tag will be the same tag.
-
With the Code drop-down list, source-branch and deployed-tag will both be the name of branch or tag selected from the drop-down list.
Example: If the Dev environment is deploying the master branch and you drag Dev code to Stage, the code-deploy arguments will be like:
post-code-deploy mysite test master tags/2011-11-05 mysite@svn-3.devcloud.hosting.acquia.com:mysite.git git
The post-code-update hook runs in response to code commits. When you push commits to a Git branch, the post-code-update hooks runs for each environment that is currently running that branch.
The arguments for post-code-update are the same as for post-code-deploy, with the source-branch and deployed-tag arguments both set to the name of the environment receiving the new code.
The post-db-copy hook is run whenever you use the Workflow page to copy a database from one environment to another.
Usage: post-db-copy site target-env db-name source-env
- site: The site name. This is the same as the Acquia Cloud username for the site.
- target-env: The environment to which the database was copied.
- db-name: The name of the database that was copied. See below.
- source-env: The environment from which the database was copied.
db-name is not the actual MySQL database name but rather the common name for the database in all environments. Use the drush ah-sql-cli to connect to the actual MySQL database, or use the drush ah-sql-connect command to convert the site name and target environment into the specific MySQL database name and credentials. (The drush sql-cli and sql-connect commands work too, but only if your Drupal installation is set up correctly.)
Example: To "scrub" your production database by removing all user accounts every time it is copied into your Stage environment, put this script into /hooks/test/post-db-copy/delete-users.sh:
#!/bin/bash
site=$1
env=$2
db=$3
echo "DELETE FROM users" | drush @$site.$env ah-sql-cli --db=$db
The post-files-copy hook is run whenever you use the Workflow page to copy the user-uploaded files directory from one environment to another.
Usage: post-files-copy site target-env source-env
- site: The site name. This is the same as the Acquia Cloud username for the site.
- target-env: The environment to which files were copied.
- source-env: The environment from which the files were copied.
Example: When you use the Workflow page to drag files from Prod to Dev, the files-copy hook will be run like:
post-files-copy mysite prod dev
The pre-site-code-deploy hook is run before code is deployed to a specific site via the Acquia Cloud UI or API. This is a site-level deployment hook that allows you to prepare a site for deployment, such as enabling maintenance mode.
Usage: pre-site-code-deploy site target-env source-branch deployed-tag repo-url repo-type site-name extra-args
- site: The site name. This is the same as the Acquia Cloud username for the site.
- target-env: The environment to which code is being deployed.
- source-branch: The code branch or tag being deployed.
- deployed-tag: The code branch or tag being deployed.
- repo-url: The URL of your code repository.
- repo-type: The version control system your site is using; "git".
- site-name: The specific site name being deployed to.
- extra-args: Optional parameters passed from the Acquia Cloud UI or API. Empty string if none provided.
Example: When deploying code to a site via the Cloud UI or API, the pre-site-code-deploy hook will be run like:
pre-site-code-deploy mysite prod master tags/2026-06-29 mysite@svn-3.prod.hosting.acquia.com:mysite.git git mysitename ""
The post-site-code-deploy hook is run after code has been deployed to a specific site via the Acquia Cloud UI or API. This is a site-level deployment hook that allows you to perform post-deployment tasks, such as disabling maintenance mode or running database updates.
Usage: post-site-code-deploy site target-env source-branch deployed-tag repo-url repo-type site-name extra-args
- site: The site name. This is the same as the Acquia Cloud username for the site.
- target-env: The environment to which code was deployed.
- source-branch: The code branch or tag that was deployed.
- deployed-tag: The code branch or tag that was deployed.
- repo-url: The URL of your code repository.
- repo-type: The version control system your site is using; "git".
- site-name: The specific site name that was deployed to.
- extra-args: Optional parameters passed from the Acquia Cloud UI or API. Empty string if none provided.
The extra-args parameter allows you to pass custom parameters from the Cloud UI or API to trigger specific behaviors in your hook scripts, such as running database updates.
Example: When deploying code to a site with extra arguments requesting database updates, the post-site-code-deploy hook will be run like:
post-site-code-deploy mysite prod master tags/2026-06-29 mysite@svn-3.prod.hosting.acquia.com:mysite.git git mysitename "update-db"
The pre-site-wipe hook is run before a site's database and files are wiped from an environment. This allows you to perform backups or other preparatory actions before the site data is removed.
Usage: pre-site-wipe app-name stage
- app-name: The application name for the site.
- stage: The environment stage (dev, test, or prod) from which the site will be wiped.
The post-site-wipe hook is run after a site's database and files have been wiped from an environment. This allows you to perform cleanup, notifications, or initialization of a fresh environment.
Usage: post-site-wipe app-name stage
- app-name: The application name for the site.
- stage: The environment stage (dev, test, or prod) from which the site was wiped.
The post-site-instance-duplicate hook is run after a site instance has been duplicated to create a new environment. This allows you to perform post-duplication configuration, data scrubbing, or environment-specific setup.
Usage: post-site-instance-duplicate app-name stage source-site-name
- app-name: The application name for the target site.
- stage: The environment stage (dev, test, or prod) of the target environment.
- source-site-name: The name of the source site that was duplicated.
The post-site-associate hook is run after a site has been associated with an environment. This allows you to perform initialization tasks, configure environment-specific settings, or set up integrations.
Usage: post-site-associate app-name stage site-name
- app-name: The application name for the site.
- stage: The environment stage (dev, test, or prod) with which the site was associated.
- site-name: The name of the site that was associated.