diff --git a/.vuepress/public/img/docs/approvals.png b/.vuepress/public/img/docs/approvals.png index ebcddea..1bb8011 100644 Binary files a/.vuepress/public/img/docs/approvals.png and b/.vuepress/public/img/docs/approvals.png differ diff --git a/docs/README.md b/docs/README.md index 116fdf9..4903a3f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -862,20 +862,21 @@ Users can specify on deployments and Helm charts how many approvals do they have * __non-blocking__ - multiple deployments/helm releases can be queued for approvals, the ones without specified approvals will be auto updated. * __extensible__ - current implementation focuses on Slack but additional approval collection mechanisms are trivial to implement. -* __out of the box Slack integration__ - the only needed Keel configuration is Slack auth token, Keel will start requesting approvals and users will be able to approve. +* __out of the box Slack integration__ - the only needed Keel configuration is Slack tokens, Keel will start requesting approvals and users will be able to approve. * __stateful__ - uses SQLite for persistence so even after updating itself (restarting) it will retain existing info. * __self cleaning__ - expired approvals will be removed after deadline is exceeded. ### Enabling approvals Approvals are enabled by default but currently there is only one way to approve/reject updates: -Slack - commands like: +Slack - bot mentions like: -* `keel get approvals` - get all pending/approved/rejected approvals -* `keel approve ` - approve specified request. -* `keel reject ` - reject specified request. +* `@keel get approvals` - get all pending/approved/rejected approvals +* `@keel approve ` - approve specified request. +* `@keel reject ` - reject specified request. -Make sure you have set `export SLACK_TOKEN=` environment variable for Keel deployment. +Make sure you have set `export SLACK_BOT_TOKEN=` and +`export SLACK_APP_TOKEN=`environment variable for Keel deployment. If you wish to specify a special channel for approval requests, supply `SLACK_APPROVALS_CHANNEL=` environment variable and then invite Keel bot to that channel. @@ -930,36 +931,104 @@ keel: tag: image.tag ``` -### Configuring approvals with Slack + +### Configuring Slack Slack configuration can be sometimes quite confusing. If something has changed, please create an issue. -#### Step 1: adding bot app and getting token +#### Step 1: creating an application (bot) + +Visit https://api.slack.com/apps and create a new application from a manifest file and copy/paste the following manifest: + +````json +{ + "display_information": { + "name": "keel" + }, + "features": { + "bot_user": { + "display_name": "keel", + "always_online": false + } + }, + "oauth_config": { + "scopes": { + "bot": [ + "app_mentions:read", + "channels:read", + "chat:write", + "users:read", + "channels:history" + ] + } + }, + "settings": { + "event_subscriptions": { + "bot_events": [ + "app_mention" + ] + }, + "interactivity": { + "is_enabled": true + }, + "org_deploy_enabled": false, + "socket_mode_enabled": true, + "token_rotation_enabled": false + } +} +```` + +Bot scopes explanation + - `app_mentions:read` - allows the bot to read messages that mention the bot + - `channels:read` - allows the bot to list the available channels on which the bot is invited into. This is used to retrieve the channel identifier from the approval channel name. + - `chat:write` - allows the bot to write to the channel it is invited to. + - `users:read` - allows the bot to read user information, this is needed to retrieve the bot identifier from the bot name and ensure that we found the bot. + - `channels:history` - allows the bot to read the channel history. This is used to retrieve and update an approval message with the latest information. + +Note: The needed scopes may vary depending on the channel type. (private or public). For private channel, the scope `groups:` should be used instead. -Go to your Slack apps page: https://[your-slack-community].slack.com/apps/A0F7YS25R-bots?page=1 +#### Step 2: Install the app -![Slack bots](/img/docs/slack-bots.png) +Once the application created, it can be installed on the wanted workspace. -Set name to Keel +This can be done under `Settings > Install App` menu. -![Slack bot name](/img/docs/slack-bot-name.png) +#### Step 3: Invite the bot +The bot must be invited into all channels (the channel given in the __SLACK_APPROVALS_CHANNEL__ and all channels given in __SLACK_CHANNELS__). -#### Step 2: supplying token to Keel +This can be done directly in slack, by mentioning the bot into a channel. -Use provided token as an environment variable in Keel's deployment: +#### Step 4: Supplying bot token to Keel -`SLACK_TOKEN=token` +A *bot* token was automatically created since the step 1 with the scopes from the manifest file. The token can be seen under the `Features > OAuth & Permissions` menu of the application settings page. + +This token can be used as value for the __SLACK_BOT_TOKEN__ environment variable. + +#### Step 5: Create an App level token + +Unlike the bot token, the application level token is not generated automatically. + +In the application settings, under the `Basic Information` menu, go to the `App-Level Tokens` settings and generate a new scoped token. + +The token must define the following scopes: +- `authorizations:read` +- `connections:write` + +The token can be used as value for the __SLACK_APP_TOKEN__ environment variable. + +Congratulations! Your slack bot is configured. ### Approving through Slack example Keel will send notifications to your Slack group about pending approvals. Approval process is as simple as replying to Keel: -- Approve: `keel approve default/whr:0.4.12` -- Reject it: `keel reject default/whr:0.4.12` +- Approve: `@keel approve default/whr:0.4.12` +- Reject it: `@keel reject default/whr:0.4.12` Example conversation: +//TODO image ![Approvals](/img/docs/approvals.png) ### Approving through Hipchat example @@ -1114,7 +1183,11 @@ Webhook payload sample: ![Slack notifications](/img/docs/slack-notifications.png) -First, get a Slack token, info about that can be found in the [docs](https://get.slack.help/hc/en-us/articles/215770388-Create-and-regenerate-API-tokens). Then, provide token via __SLACK_TOKEN__ environment variable. You should also provide __SLACK_CHANNELS__ environment variable with a comma separated list of channels where these notifications should be delivered to. +First slack must be configured, see [Configuring Slack](#configuring-slack) + +You should also provide __SLACK_CHANNELS__ environment variable with a comma separated list of channels where these notifications should be delivered to. + +Note that the bot must be invited into all channels provided to that environment variable. Keel will be sending messages when deployment updates succeed or fail.