semantic-release-slack-bot

semantic-release plugin to get release notifications on slack from a slack bot

Install

Add the plugin to your npm-project:

$ npm install semantic-release-slack-bot -D

Slack App/Webhook Usage

The corresponding slack app has to be installed in your slack workspace as well. Follow the instructions under configuration for more information.

The plugin can be configured in the semantic-release configuration file:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "semantic-release-slack-bot",
      {
        "notifyOnSuccess": false,
        "notifyOnFail": false,
        "slackWebhook": "https://my-webhook.com",
        "branchesConfig": [
          {
            "pattern": "lts/*",
            "notifyOnFail": true
          },
          {
            "pattern": "master1",
            "notifyOnSuccess": true,
            "notifyOnFail": true
          }
        ]
      }
    ]
  ]
}

With this example:

• Slack notification will always be sent using the "https://my-webhook.com" webhook url
• Slack notifications are sent on a failure release from branches matching "lts/*"
• Slack notifications are sent on a failure or successful release from branch "master"
• Slack notifications are skipped on all other branches

Note

The official documentation says that a developer cannot override the default name, channel or icon that are associated with the webhook, but some users of this library reported that they were able to.

• use slackName (or SLACK_NAME env var) for overriding slack app name
• use slackIcon (or SLACK_ICON env var) for overriding slack app icon
• use slackChannel (or SLACK_CHANNEL env var) for overriding slack channel

WARNING: This is not mentioned in the official documentation, so use at your own risk.

Slack Access Token/Channel Usage

This configuration can be used with a bot Slack Access token with minimum permissions of chat:write.

The plugin can be configured in the semantic-release configuration file:

{
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    [
      "semantic-release-slack-bot",
      {
        "notifyOnSuccess": false,
        "notifyOnFail": false,
        "slackToken": "token",
        "slackChannel": "my-channel-name",
        "branchesConfig": [
          {
            "pattern": "lts/*",
            "notifyOnFail": true
          },
          {
            "pattern": "master1",
            "notifyOnSuccess": true,
            "notifyOnFail": true
          }
        ]
      }
    ]
  ]
}

With this example:

• Slack notification will always be sent to the channel "#my-channel-name"
• Slack notifications are sent on a failure release from branches matching "lts/*"
• Slack notifications are sent on a failure or successful release from branch "master"
• Slack notifications are skipped on all other branches

Screenshots

Configuration

Slack app installation

The plugin uses a slack webhook which you get by adding the slack app to your slack workspace. Register the app using the button below or this link.

For the security concerned, feel free to create your own slack app and create a webhook or inspect the server code that does this creation for you at create-webhook.js. The only required permission for the webhook is to publish to a single channel.

Slack Webhook

Installing the app will yield you with a webhook that the app uses to publish updates to your selected channel. The Slack webhook authentication link is required and needs to be kept a secret. It should be defined in the environment variables.

Slack Access tokens

If you are creating your own slack app you can choose to use a bot access token and channel instead of the webhook with at least one of the following permission scopes.

1. chat:write with this permission scope the app/bot must be added to any channels before it can post to them
2. chat:write.public with this permission scope we can automatically post to any public channel for more information see here

Environment variables

Options can be defined in the environment where you will run semantic release. This can be done by exporting it in bash or in the user interface of your CI provider.

Alternatively, you can pass the webhook as a configuration option or use an Access Token.

Options

Function

If a function is provided with either the onSuccessFunction or onFailFunction options, it will be used for the respective slack message. The function should return an object that follows the Slack API message structure. The function is passed two objects, pluginConfig and context, the same objects that are passed to plugins.

Note: This only works with a configuration file that exports an object (see below for an example).

const slackifyMarkdown = require('slackify-markdown')
const { chunkifyString } = require('semantic-release-slack-bot/lib/chunkifier')

const onSuccessFunction = (pluginConfig, context) => {
  const releaseNotes = slackifyMarkdown(context.nextRelease.notes)
  const text = `Updates to ${
    pluginConfig.packageName
  } has been released to *Stage!*`
  const headerBlock = {
    type: 'section',
    text: {
      type: 'mrkdwn',
      text
    }
  }

  return {
    text,
    blocks: [
      headerBlock,
      ...chunkifyString(releaseNotes, 2900).map(chunk => {
        return {
          type: 'section',
          text: {
            type: 'mrkdwn',
            text: chunk
          }
        }
      })
    ]
  }
}

module.exports = {
  branches: ['master'],
  preset: 'eslint',
  plugins: [
    [
      'semantic-release-slack-bot',
      {
        notifyOnSuccess: true,
        onSuccessFunction,
        packageName: 'Testing Semantic Release'
      }
    ]
  ]
}

Templating

If a template is provided via either the onSuccessTemplate or onFailTemplate options, it will be used for the respective slack message. The template should be an object that follows the Slack API message structure. Strings within the template will have keywords replaced:

A sample configuration with template can look like this

"onSuccessTemplate": {
  "text": "A new version of $package_name with version $npm_package_version has been released at $repo_url!"
}

Helper functions

There are two helper functions exported by the chunkifier module.

chunkifyArray takes an array of strings and returns a new array based on maxLength and delimiter. delimiter is optional and defaults to newline.

chunkifyString takes a string and returns an array based on maxLength and delimiter. delimiter is optional and defaults to newline.

See respective implementation for more details.