slackapi/slack-github-action

Send data into Slack using this GitHub Action!

Slack Send GitHub Action

Send data into Slack using this GitHub Action!

Example Workflows

For examples on how to leverage this in your workflows, check out the example workflows we have.

Sending Variables

You can provide data to send with this GitHub Action from various sources:

• The default event context with a payload matching the GitHub event.
• A custom JSON payload with optional variables provided in the GitHub Action step.

The custom payload can be provided inline in your GitHub workflow or from a file, detailed with technique 1, and will be used instead of the default event context if included.

How to Send Data to Slack

This package has three different techniques to send data to Slack:

1. Send data to Slack's Workflow Builder (requires a paid Slack instance).
2. Send data via a Slack app to post to a specific channel (use an existing custom app or create a new one).
3. Send data via a Slack Incoming Webhook URL (use an existing custom app or create a new one).

The recommended way to use this action is with Slack's Workflow Builder (if you're on a paid Slack plan).

Technique 1: Slack Workflow Builder

❗️ This approach requires a paid Slack plan; it also doesn't support any text formatting

This technique sends data into Slack via a webhook URL created using Slack's Workflow builder. Follow these steps to create a Slack workflow using webhooks. The Slack workflow webhook URL will be in the form https://hooks.slack.com/workflows/.....

As part of the workflow setup, you will need to define expected variables in the payload the webhook will receive (described in the "Create custom variables" section of the docs). If these variables are missing in the payload, an error is returned.

To match the webhook input format expected by Workflow Builder, the payload will be flattened and stringified (all nested keys are moved to the top level) before being sent. The default delimiter used to flatten payloads is a period (".") but should be changed to an underscore ("_") using the payload-delimiter parameter if you're using nested payloads as input values in your own workflows.

Setup

• Create a Slack workflow webhook.
• Copy the webhook URL (https://hooks.slack.com/workflows/....) and add it as a secret in your repo settings named SLACK_WEBHOOK_URL.
• Add a step to your GitHub action to send data to your Webhook.
• Configure your Slack workflow to use variables from the incoming payload from the GitHub Action. You can select where you want to post the data and how you want to format it in Slack's workflow builder interface.

Usage

Add this Action as a step to your project's GitHub Action Workflow file:

- name: Send GitHub Action trigger data to Slack workflow
  id: slack
  uses: slackapi/slack-github-action@v1.27.0
  with:
    payload-delimiter: "_"
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

or

- name: Send custom JSON data to Slack workflow
  id: slack
  uses: slackapi/slack-github-action@v1.27.0
  with:
    # This data can be any valid JSON from a previous step in the GitHub Action
    payload: |
      {
        "key": "value",
        "foo": "bar"
      }
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

or

If the payload is provided it will take preference over payload-file-path

- name: Send custom JSON data to Slack workflow
  id: slack
  uses: slackapi/slack-github-action@v1.27.0
  with:
    payload-file-path: "./payload-slack-content.json"
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

To send the payload file JSON as is, without replacing templated values with github.context or github.env, set payload-file-path-parsed to false. Default: true.

- name: Send custom JSON data to Slack workflow
  id: slack
  uses: slackapi/slack-github-action@v1.27.0
  with:
    payload-file-path: "./payload-slack-content.json"
    payload-file-path-parsed: false
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

Technique 2: Slack App

By creating a new Slack app or using an existing one, this approach allows your GitHub Actions job to post a message in a Slack channel or direct message by utilizing the chat.postMessage API method. Using this approach you can instantly post a message without setting up Slack workflows.

Setup

• Create a Slack App for your workspace (alternatively use an existing app you have already created and installed).
• Add the chat:write bot scope under OAuth & Permissions.
• Install the app to your workspace.
• Copy the app's Bot Token from the OAuth & Permissions page and add it as a secret in your repo settings named SLACK_BOT_TOKEN.
• Invite the bot user into the channel you wish to post messages to (/invite @bot_user_name).

Usage

Add this Action as a step to your project's GitHub Action Workflow file:

- name: Post to a Slack channel
  id: slack
  uses: slackapi/slack-github-action@v1.27.0
  with:
    # Slack channel id, channel name, or user id to post message.
    # See also: https://api.slack.com/methods/chat.postMessage#channels
    # You can pass in multiple channels to post to by providing a comma-delimited list of channel IDs.
    channel-id: 'CHANNEL_ID,ANOTHER_CHANNEL_ID'
    # For posting a simple plain text message
    slack-message: "GitHub build result: ${{ job.status }}\n${{ github.event.pull_request.html_url || github.event.head_commit.url }}"
  env:
    SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

Using JSON payload for constructing a message is also available:

- name: Post to a Slack channel
  id: slack
  uses: slackapi/slack-github-action@v1.27.0
  with:
    # Slack channel id, channel name, or user id to post message.
    # See also: https://api.slack.com/methods/chat.postMessage#channels
    channel-id: 'CHANNEL_ID'
    # For posting a rich message using Block Kit
    payload: |
      {
        "text": "GitHub Action build result: ${{ job.status }}\n${{ github.event.pull_request.html_url || github.event.head_commit.url }}",
        "blocks": [
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "GitHub Action build result: ${{ job.status }}\n${{ github.event.pull_request.html_url || github.event.head_commit.url }}"
            }
          }
        ]
      }
  env:
    SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

Update the message

If you would like to notify the real-time updates on a build status, you can modify the message your build job posted in the subsequent steps. In order to do this, the steps after the first message posting can have update-ts: ${{ steps.slack.outputs.ts }} in their settings. With this, the step updates the already posted channel message instead of posting a new one.

Please note that the message update step does not accept a channel name. Set a channel ID for the steps for the actions that update messages.

- id: slack
  uses: slackapi/slack-github-action@v1.27.0
  with:
    # The following message update step does not accept a channel name.
    # Setting a channel ID here for consistency is highly recommended.
    channel-id: "CHANNEL_ID"
    payload: |
      {
        "text": "Deployment started (In Progress)",
        "attachments": [
          {
            "pretext": "Deployment started",
            "color": "dbab09",
            "fields": [
              {
                "title": "Status",
                "short": true,
                "value": "In Progress"
              }
            ]
          }
        ]
      }
  env:
    SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
- uses: slackapi/slack-github-action@v1.27.0
  with:
    # Unlike the step posting a new message, this step does not accept a channel name.
    # Please use a channel ID, not a name here.
    channel-id: "CHANNEL_ID"
    update-ts: ${{ steps.slack.outputs.ts }}
    payload: |
      {
        "text": "Deployment finished (Completed)",
        "attachments": [
          {
            "pretext": "Deployment finished",
            "color": "28a745",
            "fields": [
              {
                "title": "Status",
                "short": true,
                "value": "Completed"
              }
            ]
          }
        ]
      }
  env:
    SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

Reply to a message

If you want to post a message as a threaded reply, you can populate the payload with a thread_ts field. This field should equal the ts value of the parent message of the thread. If you want to reply to a message previously posted by this Action, you can use the ts output provided as the thread_ts of a consequent threaded reply, e.g. "thread_ts": "${{ steps.deployment_message.outputs.ts }}".

Please note that reply to a message does not accept a channel name. Set a channel ID for the actions that reply to messages in thread.

- id: deployment_message
  uses: slackapi/slack-github-action@v1.27.0
  with:
    channel-id: "CHANNEL_ID"
    payload: |
      {
        "text": "Deployment started (In Progress)"
      }
  env:
    SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
- uses: slackapi/slack-github-action@v1.27.0
  with:
    # Unlike the step posting a new message, this step does not accept a channel name.
    # Please use a channel ID, not a name here.
    channel-id: "CHANNEL_ID"
    payload: |
      {
        "thread_ts": "${{ steps.deployment_message.outputs.ts }}",
        "text": "Deployment finished (Completed)"
      }
  env:
    SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

Technique 3: Slack Incoming Webhook

This approach allows your GitHub Actions job to post a message to a Slack channel or direct message by utilizing Incoming Webhooks.

Incoming Webhooks conform to the same rules and functionality as any of Slack's other messaging APIs. You can make your posted messages as simple as a single line of text, or make them really useful with interactive components. To make the message more expressive and useful use Block Kit to build and test visual components.

Setup

• Create a Slack App for your workspace (alternatively use an existing app you have already created and installed).
• Add the incoming-webhook bot scope under OAuth & Permissions.
• Install the app to your workspace (you will select a channel to notify).
• Activate and create a new webhook under Incoming Webhooks.
• Copy the Webhook URL from the Webhook you just generated add it as a secret in your repo settings named SLACK_WEBHOOK_URL.

Usage

- name: Send custom JSON data to Slack workflow
  id: slack
  uses: slackapi/slack-github-action@v1.27.0
  with:
    # For posting a rich message using Block Kit
    payload: |
      {
        "text": "GitHub Action build result: ${{ job.status }}\n${{ github.event.pull_request.html_url || github.event.head_commit.url }}",
        "blocks": [
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "GitHub Action build result: ${{ job.status }}\n${{ github.event.pull_request.html_url || github.event.head_commit.url }}"
            }
          }
        ]
      }
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
    SLACK_WEBHOOK_TYPE: INCOMING_WEBHOOK

HTTPS Proxy

If you need to use a proxy to connect with Slack, you can use the HTTPS_PROXY (or https_proxy) environment variable. In this example we use the Slack App technique, but configuring a proxy works the same way for all of them:

- name: Post to a Slack channel via a proxy
  id: slack
  uses: slackapi/slack-github-action@v1.27.0
  with:
    channel-id: 'CHANNEL_ID'
    slack-message: 'This message was sent through a proxy'
  env:
    SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
    # Set the HTTPS_PROXY environment variable to whatever your policy requires
    HTTPS_PROXY: 'http://proxy.example.org:8080'

Contributing

See CONTRIBUTING.

License

See LICENSE.