npm package: @mrackoa/backstage-plugin-scaffolder-backend-module-slack
Description: The slack module for @backstage/plugin-scaffolder-backend
Latest version: 5.0.0

# 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:

```shell
yarn add --cwd packages/backend @mrackoa/backstage-plugin-scaffolder-backend-module-slack
```

Add the module to the scaffolder:

```typescript
// packages/backend/src/index.ts

backend.add(import('@mrackoa/backstage-plugin-scaffolder-backend-module-slack'));
```

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.

```yaml
# 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

```yaml
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
```