Skip to content

Latest commit

 

History

History
240 lines (190 loc) · 5.27 KB

README.md

File metadata and controls

240 lines (190 loc) · 5.27 KB
Raw

Slack Plugin

Post your release notes to a slack channel.

Example slack release notes

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

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" }]
  ]
}

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"]
      }
    ]
  ]
}

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"
      }
    ],
    [
      "slack",
      {
        "url": "https://url-to-your-slack-hook.com",
        // Disable tagging when posting a message
        "atTarget": false
      }
    ]
  ]
}

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 }
    ]
  ]
}

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"
      }
    ]
  ]
}

username

Username to post the message as.

{
  "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"
      }
    ]
  ]
}

NOTE: If both iconUrl and iconEmoji are specified only iconUrl 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:"
      }
    ]
  ]
}

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"]
      }
    ]
  ]
}

Read here for more details.

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.

  1. Create the app
  2. From your app's Basic Information page go to Permissions => Bot Token Scopes and add chat:write and file:write (Optionally add chat:write.customize to use the username and icon options)
  3. Copy the Bot User OAuth Access Token into your .env file and store it as SLACK_TOKEN
  4. 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.

This could be your code's logo or one of our logos.