From 9ee8b7a530800f5e09d3db5aabd52191f0d5fd60 Mon Sep 17 00:00:00 2001 From: Tiffany K Date: Tue, 23 Jan 2018 12:09:26 -0800 Subject: [PATCH] fix(687): Add Slack notifications settings for user and cluster admin (#140) * fix(687): Add Slack notifications settings for user and cluster admin * fix: Add bot link * fix: Combine notification examples --- docs/about/contributing.md | 3 +- docs/cluster-management/configure-api.md | 13 +++++- docs/index.md | 8 ++-- docs/user-guide/configuration/settings.md | 57 ++++++++++++++++++++--- 4 files changed, 69 insertions(+), 12 deletions(-) diff --git a/docs/about/contributing.md b/docs/about/contributing.md index c35a9c16..0be958bf 100644 --- a/docs/about/contributing.md +++ b/docs/about/contributing.md @@ -71,7 +71,7 @@ The **[screwdriver][api-repo]** repo is the core of screwdriver, providing the A * **[Build bookends][build-bookend-repo]** allow a user to create setup and teardown steps for builds. -* The API can also send notifications to users. [notifications-base][notifications-base-repo] is the base class for defining the behavior between screwdriver and notifications plugins, like [email notifications][notifications-email-repo]. +* The API can also send notifications to users. [notifications-base][notifications-base-repo] is the base class for defining the behavior between screwdriver and notifications plugins, like [email notifications][notifications-email-repo] and [slack notifications][notifications-slack-repo]. ### [Launcher][launcher-repo] @@ -196,6 +196,7 @@ The organization [screwdriver-cd-test][screwdriver-cd-test-org] contains various [models-repo]: https://github.com/screwdriver-cd/models [notifications-base-repo]: https://github.com/screwdriver-cd/notifications-base [notifications-email-repo]: https://github.com/screwdriver-cd/notifications-email +[notifications-slack-repo]: https://github.com/screwdriver-cd/notifications-slack [scm-base-repo]: https://github.com/screwdriver-cd/scm-base [scm-bitbucket-repo]: https://github.com/screwdriver-cd/scm-bitbucket [scm-github-repo]: https://github.com/screwdriver-cd/scm-github diff --git a/docs/cluster-management/configure-api.md b/docs/cluster-management/configure-api.md index 545a3fb0..31d30c6f 100644 --- a/docs/cluster-management/configure-api.md +++ b/docs/cluster-management/configure-api.md @@ -209,7 +209,7 @@ executor: launchVersion: stable ``` ### Notifications Plugin -We currently support [Email notifications](https://github.com/screwdriver-cd/notifications-email). +We currently support [Email notifications](https://github.com/screwdriver-cd/notifications-email) and [Slack notifications](https://github.com/screwdriver-cd/notifications-slack). #### Email Notifications @@ -226,6 +226,17 @@ notifications: Configurable authentication settings have not yet been built, but can easily be added. We’re using the [nodemailer](https://nodemailer.com/about/) package to power emails, so authentication features will be similar to any typical nodemailer setup. Contribute at: [screwdriver-cd/notifications-email](https://github.com/screwdriver-cd/notifications-email) +#### Slack Notifications + +Create a `screwdriver-bot` [Slack bot user](https://api.slack.com/bot-users) in your Slack instance. Generate a Slack token for the bot and set the `token` field with it in your Slack notifications settings. + +```yaml +# config/local.yaml +notifications: + slack: + token: 'YOUR-SLACK-USER-TOKEN-HERE' +``` + #### Custom Notifications You can create custom notification packages by extending [notifications-base](https://github.com/screwdriver-cd/notifications-base). diff --git a/docs/index.md b/docs/index.md index 6e43c3e1..3bb2ed97 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,15 +12,15 @@ is_homepage: true
+
+

User Guide

+

If you'd like to use Screwdriver to run a build, visit our User Guide.

+

Cluster Management

To find more information about managing your own Screwdriver cluster, visit the Cluster Management section.

-
-

User Guide

-

If you'd like to use Screwdriver to run a build, visit our User Guide.

-

About

To learn more about Screwdriver in general, visit the About section.

diff --git a/docs/user-guide/configuration/settings.md b/docs/user-guide/configuration/settings.md index 4c145d93..8ccb47ff 100644 --- a/docs/user-guide/configuration/settings.md +++ b/docs/user-guide/configuration/settings.md @@ -8,25 +8,70 @@ toc: url: "#settings" - title: Email url: "#email" + - title: Slack + url: "#slack" --- # Settings Configurable settings for any additional build plugins added to Screwdriver.cd. -## Email -To enable emails to be sent as a result of build events, use the email setting. -You can configure a list of one or more email addresses to contact. You can also configure when to send an email, e.g. when the build status is `SUCCESS` and/or `FAILURE`. +The settings can be set in `shared`, to apply to all jobs, or in an individual job. A job-level setting will completely override the `shared` setting. + +If you don't configure the build status, the notification will default to sending notifications on `FAILURE` only. -### Example ``` shared: - template: example/mytemplate@stable + settings: + email: [test@email.com, test2@email.com] + slack: 'mychannel' + +jobs: + main: + template: example/mytemplate@stable +``` +``` jobs: main: + template: example/mytemplate@stable + settings: + email: [test@email.com, test2@email.com] + slack: 'mychannel' +``` + +## Email +To enable emails to be sent as a result of build events, use the email setting. +You can configure a list of one or more email addresses to contact. You can also configure when to send an email, e.g. when the build status is `SUCCESS` and/or `FAILURE`. + +### Example +``` settings: email: addresses: [test@email.com, test2@email.com] statuses: [SUCCESS, FAILURE] ``` -The settings email configuration can be set in `shared`, to apply to all jobs, or in an individual job. A job `email` configuration will completely override the `shared` setting. \ No newline at end of file +## Slack +To enable Slack notifications to be sent as a result of build events, invite the `screwdriver-bot` Slack bot to your channel(s) and use the Slack setting in your Screwdriver yaml. +You can configure a list of one or more Slack channels to notify. You can also configure when to send a Slack notification, e.g. when the build status is `SUCCESS` and/or `FAILURE`. + +### Example + +This Slack setting will send Slack notifications to `mychannel` and `my-other-channel` on all build statuses: + +``` + settings: + slack: + channels: + - 'mychannel' + - 'my-other-channel' + statuses: + - SUCCESS + - FAILURE + - ABORTED + - QUEUED + - RUNNING +``` + +Success notification: + +![Slack notification](../assets/slack-notification.png)