Skip to content

Latest commit

 

History

History
103 lines (73 loc) · 3.74 KB

README.md

File metadata and controls

103 lines (73 loc) · 3.74 KB
Raw

backstage-plugin-scaffolder-backend-module-slack

This is a slack actions plugin for the scaffolder-backend in Backstage.

This contains a collection of actions for using to send Slack messages.

Prerequisites

  • Node must be installed in the environment your Backstage instance is running in, but it will most likely already be there since your Backstage instance runs in Node.

  • You must either have a Slack app installed with the proper OAuth scopes granted and an OAuth Bot Token to use, or a Slack webhook URL to send messages to.

Using a Slack Webhook URL

In order to use a Slack Webhook URL, follow the instructions in Slack's documentation to create a webhook URL that can receive messages. https://api.slack.com/messaging/webhooks

Using a Bot OAuth Token

In order to use a Slack App with the proper OAuth Token Scopes, follow the instructions in Slack's documentation to create a Slack App with the proper OAuth scopes granted to it. https://api.slack.com/start/quickstart

You'll need the following scopes:

  • channels:join
  • chat:write
  • chat:write.public
  • im:write
  • channels:read

Alternatively, there is an app manifest provided in the slack-app-manifest.yaml of this repository that you can use to create an app with the proper permissions already granted.

Getting Started

In the root directory of your Backstage project:

yarn add --cwd packages/backend @mdude2314/backstage-plugin-scaffolder-backend-module-slack

Add the actions you'd like to the scaffolder:

// packages/backend/src/index.ts

import {
  sendSlackMessageModule
} from '@mdude2314/backstage-plugin-scaffolder-backend-module-slack'

...

backend.add(sendSlackMessageModule());

Add a Slack configuration section to your app-config.yaml.

You can omit this by providing a webhook URL in the input of the step in your scaffolder template, but it must be present in one place or the other.

# app-config.yaml

slack:
  # This is required if you're using a Slack webhook URL to send messages and you
  # don't intend to supply the webhook URL from the action inputs
  webhookUrl: "https://example.com"

  # These are required if you are using the Slack API to send messages and you
  # don't intend to supply these from the action inputs
  token: ${SLACK_TOKEN}
  conversationId: ABC123 # The ID of the conversation to send messages to. Either this or the conversationName are required here if you don't intend to supply either from the action inputs
  conversationName: general # The name of the conversation to send messages to. Either this or the conversationId are rqeuired here if you don't intend to supply either from the action inputs

Example of using the send message action in a template

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: slack-message-demo
  title: My Slack message demo
  description: Send a message via Slack
spec:
  owner: mdude2314
  type: service

  steps:
    # this step is an example of using the webhook action
    - id: send-slack-message
      name: Send slack message via Slack webhook
      action: slack:sendMessage:webhook
      input:
        message: "Hello, world!"
        webhookUrl: "https://example.com" # optional if the URL is supplied in the app-config.yaml

    # this step is an example of using the conversation action
    - id: send-slack-message
      name: Send slack message via Slack API
      action: slack:sendMessage:conversation
      input:
        message: "Hello, world!"
        conversationId: "abc123" # optional if the conversationId is supplied in the app-config.yaml, or the conversationName is supplied at all
        conversationName: "general" # optional if the conversationName is supplied in the app-config.yaml, or the conversationId is supplied at all