Use Block Kit for slack messages

plugins/slack/README.md

@@ -1,6 +1,6 @@
 # Slack Plugin
 
-Post your release notes to a slack channel
+Post your release notes to a slack channel.
 
 ## Installation
 
@@ -14,30 +14,92 @@ yarn add -D @auto-it/slack
 
 ## Usage
 
-To use the plugin include it in your `.autorc`.
+### Incoming Webhook + Token
+
+This is the easier option to set up, but it has less features than [app auth](#app-auth-token).
+
+There are a few options on how to call/construct the webhook URL:
+
+```json
+{
+  "plugins": [
+    // Webhook URL Only:
+    // Store the hook URL in `SLACK_WEBHOOK_URL` so you don't commit it
+    "slack",
+    // Incoming  Webhook URL + Token:
+    // Set generic app hook URL in `.autorc` as `url` and set the
+    // `SLACK_TOKEN` variable available on your environment.
+    //
+    // This token will be added to the URL as a query string parameter.
+    ["slack", { "url": "https://url-to-your-slack-hook.com" }]
+  ]
+}
+```
+
+[Read more about Slack incoming webhooks here.](https://api.slack.com/messaging/webhooks)
+
+### App Auth Token
+
+An incoming webhook can work for most situations but to enable a better integration we need an app auth token. This enables us to:
+
+- Upload text snippets for code blocks in release notes
+- Post to multiple channels
+
+For this to work you need to create a token with the following permissions:
+
+- `files:write`
+- `chat:write`
+
+Set the `auth` option to `app` and the `SLACK_TOKEN` will be used to authenticate as an app.
 
 ```json
 {
   "plugins": [
-    // or
-    ["slack", { "url": "https://url-to-your-slack-hook.com" }],
-    // or
-    ["slack", "https://url-to-your-slack-hook.com"],
-    // or
     [
       "slack",
-      { "url": "https://url-to-your-slack-hook.com", "atTarget": "here" }
-    ],
-    // Below: Uses slack hook set in process.env.SLACK_WEBHOOK_URL
-    "slack"
+      {
+        "auth": "app",
+        "channels": ["app-update-channel", "private-team-channel"]
+      }
+    ]
   ]
 }
 ```
 
-This URL should be to you webhook. Store it in `SLACK_WEBHOOK_URL` for more security. If you require a token to post to a slack hook, make sure you have a `SLACK_TOKEN` variable available on your environment. This token will be added to eh URL as a query string parameter.
+[Read about creating an installing apps.](https://api.slack.com/start/overview#creating)
 
 ## Options
 
+### atTarget
+
+Who to tag when posting a message.
+Defaults to `channel`.
+
+Some less chatty options are:
+
+```json
+{
+  "plugins": [
+    [
+      "slack",
+      {
+        "url": "https://url-to-your-slack-hook.com",
+        // Only tag people online
+        "atTarget": "here"
+      }
+    ],
+    [
+      "slack",
+      {
+        "url": "https://url-to-your-slack-hook.com",
+        // Tag a custom group, like the channel admin
+        "atTarget": "channel-admin"
+      }
+    ]
+  ]
+}
+```
+
 ### publishPreRelease
 
 If you are using a `prerelease` branch like `next`, Slack will not post a message by default.
@@ -50,7 +112,7 @@ However, if you would like to configure it such that Slack _does_ post on prerel
     [
       "slack",
       { "url": "https://url-to-your-slack-hook.com", "publishPreRelease": true }
-    ],
+    ]
   ]
 }
 ```
@@ -64,8 +126,32 @@ Additional Title to add at the start of the slack message.
   "plugins": [
     [
       "slack",
-      { "url": "https://url-to-your-slack-hook.com", "title": "My Cool Project" }
-    ],
+      {
+        "url": "https://url-to-your-slack-hook.com",
+        "title": "My Cool Project"
+      }
+    ]
   ]
 }
 ```
+
+### channels (App Auth Only)
+
+Channel, private group, or IM channel to send message to.
+Can be an encoded ID, or a name.
+
+```json
+{
+  "plugins": [
+    [
+      "slack",
+      {
+        "auth": "app",
+        "channels": ["app-update-channel", "private-team-channel"]
+      }
+    ]
+  ]
+}
+```
+
+[Read here for more details.](https://api.slack.com/methods/chat.postMessage#channels)