michaelbot

Michael

Announce deploys in Slack channels.

Installation

First you need to add a new slash command for your team:

1. Go to Custom Integrations and click on "New Command"
2. In the "Command" field type in /deploy — this will be your new Slack command to start, finish and list deploys in channel
3. Fill in "URL" field with an URL where michael is deployed
4. Set "Method" to POST
5. Copy the content of "Token" field, this will be needed to authenticate incoming requests

You may also like to customize name, icon and include this command into autocomplete list.

Now the server part. To execute a slash command Slack sends a request to an URL associated with it and outputs the response. Slack requires this URL to be an HTTPS, so you will need some reverse-proxy (such as nginx, caddy, etc.) configured to serve HTTPS requests. Self-signed certificates won't work for Slack, Letsencrypt might be a good option to obtain a real one.

Now compile and run the server (assuming that you have go installed):

go get github.com/adjust/michaelbot
SLACK_TOKEN=<token you copied before> $GOPATH/bin/michael

This will run a server listening on 0.0.0.0:8081. Check $GOPATH/bin/michael --help to see available options.

Optionally you may provide your GitHub personal access token with repo permissions by setting GITHUB_TOKEN environment variable. This token is used to get PR details (title, description and author) and attach them to an announcement. If no token is provided only public pull requests will be have detailed information, and others will only contain a link to GitHub.

Usage

Deploys are tracked per channel. This means that different channels can run different deploys at the same time.

• /deploy status — see if there is a deploy currently running.

• /deploy <subject> — initiate a deploy in the channel. is an arbitrary string describing what's being deployed.

  If there is already a deploy announced by another user in this channel, it needs to be finished first.

  However if you already initiated a deploy the channel, you can update its subject by executing this command again.

• /deploy done — finish current deploy.

  

  You can also finish a deploy started by another user.

  

• /deploy abort — abort current deploy. If the things went wrong you might need to rollback your changes and abort current deploy.

  

  You may also provide a reason for aborting a deploy that will be kept in channel deploys log:

  /deploy abort something went wrong with deploy
  

  

Deploy status in channel topic

In addition to announcing deploys in channel you may find it useful to have a small sign in the channel topic. This way you can quickly check if it's safe to deploy. Slack deploy command uses ✅ and ⛔ to mark channel as clear for deployment and show that there is a deploy in progress. To use this feature you need to provide Slack Web API token in SLACK_WEBAPI_TOKEN environment variable and add either :white_check_mark: or :no_entry: to the channel topic. Whenever the deploy changes the deploy bot will swap these emojis.

To disable this feature without re-deploying the whole service simply remove emojis from channel topic.

User mentions in deploy subjects

You can mention one or multiple users in deploy subject.

Once the deploy is done, they all will receive a direct message from deploy bot.

Note: no notifications will be sent if the deploy has been aborted.

As in case with deploy status in channel topic, you would need to provide Slack Web API token in SLACK_WEBAPI_TOKEN environment variable to enable this feature.

Persistent deploy statuses

To keep the deploy status between service restarts you might want to use built-in BoltDB database. To do this you need to specify the path to your BoltDB file in BOLTDB_PATH environment variable.

BOLTDB_PATH=/path/to/your/bolt.db $GOPATH/bin/michael

Deploy history

To see the history of deploys in channel run /deploy history in this channel and click the link returned by bot.

This will open a page in your browser with all deploys that were ever announced in this channel.

* suddendef was deploying https://github.com/adjust/michaelbot/pull/15 since 24 Aug 16 20:54 UTC until 24 Aug 16 20:54 UTC
* suddendef was deploying https://github.com/adjust/michaelbot/pull/15 https://github.com/adjust/michaelbot/pull/11 since 24 Aug 16 20:54 UTC until 24 Aug 16 20:55 UTC
* suddendef was deploying history since 25 Aug 16 08:35 UTC until 25 Aug 16 08:35 UTC
* suddendef was deploying https://github.com/adjust/michaelbot/pull/19 since 25 Aug 16 08:35 UTC until 25 Aug 16 08:35 UTC

Authorization and authentication

While handling the /deploy history command deploy bot generates a one-time token that grants access to current channel deploy history. This access is being granted for the next 30 days and can be renewed at any time by requesting and opening a link to history in the same channel.

Deploy bot uses JSON Web Tokens (JWT) to store channel access lists. A secret key to sign JWT can be set via HISTORY_AUTH_SECRET environment variable. If there was no secret provided, deploy bot generates a random string and writes it into the log. On next start you should use this string as a value for HISTORY_AUTH_SECRET, otherwise all issued authorizations will be revoked.

Why Michael?

Because Buffer might be not the best name for such tool.

License

This software is distributed under LGPLv3 license. You can find the full text in LICENSE.