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

@@ -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

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).

docs/index.md

@@ -12,15 +12,15 @@ is_homepage: true
 </div>
 
 <div class="row">
+    <div class="col-xs-6 col-md-4 ug">
+        <h2>User Guide</h2>
+        <p>If you'd like to use Screwdriver to run a build, visit our <a href="http://docs.screwdriver.cd/user-guide/quickstart">User Guide</a>.</p>
+    </div>
     <div class="col-xs-6 col-md-4 cm">
         <h2>Cluster Management</h2>
         <p>To find more information about managing your own Screwdriver cluster,
         visit the <a href="http://docs.screwdriver.cd/cluster-management">Cluster Management</a> section.</p>
     </div>
-    <div class="col-xs-6 col-md-4 ug">
-        <h2>User Guide</h2>
-        <p>If you'd like to use Screwdriver to run a build, visit our <a href="http://docs.screwdriver.cd/user-guide/quickstart">User Guide</a>.</p>
-    </div>
     <div class="col-xs-6 col-md-4 about">
         <h2>About</h2>
         <p>To learn more about Screwdriver in general, visit the <a href="http://docs.screwdriver.cd/about">About</a> section.</p>

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: [[email protected], [email protected]]
+        slack: 'mychannel'
+
+jobs:
+    main:
+        template: example/mytemplate@stable
+```
 
+```
 jobs:
     main:
+        template: example/mytemplate@stable
+        settings:
+            email: [[email protected], [email protected]]
+            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: [[email protected], [email protected]]
                 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.
+## 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)