Deploy Hooks

Last Updated: 23 February 2015

deploy deploy hook git hook notification

Deploy hooks allow you to receive a notification whenever a new version of your app is pushed to Heroku. It’s useful to keep you and your team informed about deploys, while it can also be used to integrate different systems together.

After one or more hooks are setup, git push will show that they are scheduled to run:

$ git push heroku master
...

-----> Heroku receiving push
-----> Rails app detected
       Compiled slug size is 76K
-----> Launching...... done
-----> Deploy hooks scheduled, check output in your logs
       http://myapp.heroku.com deployed to Heroku

Hook output and errors appear in your application’s logs:

$ heroku logs
...
2011-03-15T15:07:29-07:00 heroku[deployhooks]: Sent email notification to me@example.com

Each deploy hook is its own add-on. This allows you to pick and choose one or more that you want. The deploy hooks include:

Email

This hook will send one or more emails. You can specify the subject and body, as follows:

$ heroku addons:add deployhooks:email \
    --recipient=me@example.com \
    --subject="Myapp Deployed" \
    --body="{{user}} deployed app"
Adding deployhooks:email to myapp...Done.

Email multiple recipients by adding additional email addresses separated by spaces.

IRC

An IRC bot will connect to the specified server and message the room.

$ heroku addons:add deployhooks:irc \
    --server=irc.freenode.net \
    --room=devlounge \
    --nick=mydeploybot \
    --password=secret \
    --message="{{user}} deployed app"
Adding deployhooks:irc to myapp...Done.

Nick and password are optional. You can also set the server port by sending port=1234.

Basecamp

This hook will post a message to any Basecamp account you specify, under a certain project and post category (both specified by the name).

$ heroku addons:add deployhooks:basecamp \
    --url=http://myaccount.basecamphq.com \
    --username=00000000 \
    --project=myapp \
    --category=deploys \
    --title="{{user}} deployed myapp" \
    --body="check it at {{url}}"
Adding deployhooks:basecamp to myapp...Done.

NOTE: Please put your API Key under the username param above.

Campfire

Have any Campfire room receive an automated message when your app is pushed.

$ heroku addons:add deployhooks:campfire \
    --url=mycampfiresubdomain \
    --ssl=1 \
    --api_key=0000000 \
    --room=devlounge \
    --message="{{user}} deployed myapp"
Adding deployhooks:campfire to myapp...Done.

HipChat

This hook wil post a message to a HipChat room of your choice on app push. An authentication key is required for Heroku to access your HipChat account. To create one, fill out the form found in API Auth Tokens (available to group admins only). For maximum safety, set the type to “notification”.

To make Heroku send notices to a HipChat room on deploy, do the following:

$ heroku addons:add deployhooks:hipchat \
    --auth_token=my_auth_token \
    --room="My Company's Room" \
    --message="{{user}} deployed myapp"
Adding deployhooks:hipchat to myapp...Done.

Additional optional settings are:

• from: Name of the user sending the message (default: “Heroku”).
• notify: Boolean value (1 or 0) indicating whether the message should trigger a notification to users in the room (default: “1”).
• color: The background color of the message. (default: “purple”).
• message_format : Can be set to “text” for plain text messages, or “html” to support basic tags. (default: “html”).

Check the HipChat API docs for more info on these options.

HTTP post hook

Performs an HTTP post to URL of your choice.

$ heroku addons:add deployhooks:http \
    --url=http://example.org
Adding deployhooks:http to myapp...Done.

The parameters are POSTed to your url with a mime type of application/x-www-form-urlencoded.

The parameters included in the request are the same as the variables available in the hook message: app, user, url, head, head_long, git_log and release. See below for their descriptions.

This is an example payload:

app=secure-woodland-9775&user=example%40example.com&url=http%3A%2F%2Fsecure-woodland-9775.herokuapp.com&head=4f20bdd&head_long=4f20bdd&prev_head=&git_log=%20%20*%20Michael%20Friis%3A%20add%20bar&release=v7

Customizing messages

It’s possible to use variables when defining the message, title or subject of any deploy hook attribute.

For instance, use {{user}} when you want to see who deployed, and that text will be replaced for the actual user email whenever a hook is executed.

Available variables are:

• app: the app name
• user: email of the user deploying the app
• url: the app URL (http://myapp.heroku.com or http://mydomain.com if you have custom domains enabled)
• head: short identifier of the latest commit (first seven bytes of the SHA1 git object name)
• head_long: full identifier of the latest commit
• git_log: log of commits between this deploy and the last
• release: identifier for the release (eg. v7)