Slack Plugin
Post your release notes to a slack channel.
Installation
This plugin is not included with the auto
CLI installed via NPM. To install:
npm i --save-dev @auto-it/slack # or yarn add -D @auto-it/slack
npm i --save-dev @auto-it/slack # or yarn add -D @auto-it/slack
Usage
Incoming Webhook + Token
This is the easier option to set up, but it has less features than app auth.
There are a few options on how to call/construct the webhook URL:
{ "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" }] ] }
{ "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.
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 an app 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.
{ "plugins": [ [ "slack", { "auth": "app", "channels": ["app-update-channel", "private-team-channel"] } ] ] }
{ "plugins": [ [ "slack", { "auth": "app", "channels": ["app-update-channel", "private-team-channel"] } ] ] }
Read about creating an installing apps.
Options
atTarget
Who to tag when posting a message.
Defaults to channel
.
Some less chatty options are:
{ "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" } ] ] }
{ "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.
This is done to avoid spamming your consumers every time you make a preview release.
However, if you would like to configure it such that Slack does post on prerelease, you can add the publishPreRelease
to your .autorc
like so:
{ "plugins": [ [ "slack", { "url": "https://url-to-your-slack-hook.com", "publishPreRelease": true } ] ] }
{ "plugins": [ [ "slack", { "url": "https://url-to-your-slack-hook.com", "publishPreRelease": true } ] ] }
title
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" } ] ] }
{ "plugins": [ [ "slack", { "url": "https://url-to-your-slack-hook.com", "title": "My Cool Project" } ] ] }
username
Username to post the message as.
{ "plugins": [ [ "slack", { "url": "https://url-to-your-slack-hook.com", "username": "My Project" } ] ] }
{ "plugins": [ [ "slack", { "url": "https://url-to-your-slack-hook.com", "username": "My Project" } ] ] }
iconUrl
Image url to use as the message's avatar.
{ "plugins": [ [ "slack", { "url": "https://url-to-your-slack-hook.com", "iconUrl": "http://lorempixel.com/48/48" } ] ] }
{ "plugins": [ [ "slack", { "url": "https://url-to-your-slack-hook.com", "iconUrl": "http://lorempixel.com/48/48" } ] ] }
NOTE: If both
iconUrl
andiconEmoji
are specified onlyiconUrl
will be respected
iconEmoji
Emoji code to use as the message's avatar.
{ "plugins": [ [ "slack", { "url": "https://url-to-your-slack-hook.com", "iconEmoji": ":chart_with_upwards_trend:" } ] ] }
{ "plugins": [ [ "slack", { "url": "https://url-to-your-slack-hook.com", "iconEmoji": ":chart_with_upwards_trend:" } ] ] }
channels (App Auth Only)
Channel, private group, or IM channel to send message to. Can be an encoded ID, or a name.
{ "plugins": [ [ "slack", { "auth": "app", "channels": ["app-update-channel", "private-team-channel"] } ] ] }
{ "plugins": [ [ "slack", { "auth": "app", "channels": ["app-update-channel", "private-team-channel"] } ] ] }
Creating a Slack App
There are a lot of steps to creating a Slack app and installing it. Let's go over what you'll need to do to get set up with app auth.
- Create the app
- From your app's
Basic Information
page go toPermissions => Bot Token Scopes
and addchat:write
andfile:write
(Optionally addchat:write.customize
to use theusername
andicon
options) - Copy the
Bot User OAuth Access Token
into your.env
file and store it asSLACK_TOKEN
- Install the app in the channels you want it to post to via the Slack UI
Customize the App
To make you app shine in Slack head to Basic Information
and scroll down to Display Information
.
Her you should set a description for the app and give it an icon
and color
.