Release Slack Send v2.0.0 · slackapi/slack-github-action

YAML! And more API methods! With improved erroring! And more!

Sending data to Slack can now be done with the YAML format, and that data can be sent to a Slack API method or technique of choice with the provided payload. And additional configurations can improve error handling or customize values between steps.

Breaking changes happen with this update and recommended migration strategies are detailed below. Adding this step to new workflows might prefer to follow the README instead 📚

What's changed

Both inputs of payload variables, techniques for sending the payload, additional configurations, and expected outputs were changed:

Sending variables
- Breaking changes
- Enhancements
  - Payloads can now be written in YAML
  - Payload can now be written in unwrapped JSON
Sending techniques
- Technique 1: Slack Workflow Builder
  - Breaking changes
    - The webhook type must be specified in webhook inputs
    - Payload flattening no longer happens by default
  - Enhancements
    - The webhook URL can be specified in webhook inputs
- Technique 2: Slack API method
  - Breaking changes
- Technique 3: Slack incoming webhook
  - Breaking changes
    - The webhook type must be specified for incoming webhooks
  - Enhancements
    - The webhook URL can be specified for incoming webhook
Additional configurations
- Enhancements
Expected outputs
- Breaking changes
  - The time value is now returned as the Unix epoch time
- Enhancements
  - An ok value is added to represent response success
  - A response value is added with the response data

The following sections detail these changes with recommended changes for existing GitHub workflows using this step and certain features.

If something seems off after making these changes, please feel free to open an issue for discussion! 👾

Sending variables

The source of variables remains the same, using one of the following inputs:

payload: Inputs written inline in your GitHub workflow file.
payload-file-path: Inputs gathered from a file.
No input: Uses the default event context with a payload matching the GitHub event.

⚠️ Breaking changes

Only one payload input can be provided

This Action now exits with an error if both payload and payload-file-path are provided.

Prior to updating: Both options could be provided with payload being preferred.

Recommended change: Use either payload, payload-file-path, or neither, when providing inputs. But don't include both.

Only one technique to send can be provided

This Action now exits with an error if both method and webhook techniques are provided.

Prior to updating: Both techniques could be used to send the same payload.

Recommended change: Use either method or webhook to send data, but not both.

Variable replacements no longer happen by default

This Action now sends payload provided in a payload-file-path file exactly as is.

Prior to updating: Templatized variables in input files were replaced with the matching github or env variable:

{
  "channel": "${{ env.SLACK_CHANNEL_ID }}",
  "text": "A commit was made: ${{ github.sha }}"
}

Changing the above file into something like this before being sent:

{
  "channel": "C0123456789",
  "text": "A commit was made: 3982e204d2ae590e908dd1e279e63933da566c8c"
}

Recommended change: To continue replacing templated variables provided from the step env or default GitHub event context and payload, set the payload-templated variable to true.

Payload file path parsed option was removed

This Action removed the payload-file-path-parsed input option.

Prior to updating: This option, which defaulted to true, could be set to false to avoid replacing templatized variables in a provided payload-file-path file.

Recommended change: Remove this option if it's set to false or set the new payload-templated option to true to continue parsing the provided payload.

🎁 Enhancements

Payloads can now be written in YAML

This Action now supports writing payload or payload-file-path values with YAML!

Prior to updating: Values provided as payloads had to be JSON.

Recommended change: Optional. Format the input payload value as YAML to match the surrounding steps:

- name: Post to a Slack channel
  uses: slackapi/[email protected]
  with:
    method: chat.postMessage
    token: ${{ secrets.SLACK_BOT_TOKEN }}
    payload: |
      channel: ${{ secrets.SLACK_CHANNEL_ID }}
      text: "Greetings <@channel>!"

Payload can now be written in unwrapped JSON

This Action now supports writing payload with unwrapped JSON, where surrounding braces are removed.

Prior to updating: Values provided as payloads had to be JSON.

Recommended change: Optional. Remove the surrounding braces from an existing payload value:

- name: Post to a Slack channel
  uses: slackapi/[email protected]
  with:
    method: chat.postMessage
    token: ${{ secrets.SLACK_BOT_TOKEN }}
    payload: |
      "channel": "${{ secrets.SLACK_CHANNEL_ID }}",
      "text": "Greetings <@channel>!",

Sending techniques

The techniques for sending variables remains the same, using one of the following:

Technique 1: Slack Workflow Builder
Technique 2: Slack API method
Technique 3: Slack incoming webhook

Changes for different technique might be different and are included in each of the following sections.

Technique 1: Slack Workflow Builder

⚠️ Breaking changes

The webhook type must be specified in webhook inputs

This Action now requires setting the webhook-type as a step input value.

Prior to updating: The webhook type could be omitted to send to Workflow Builder.

Recommended change: Set the webhook-type value to webhook-trigger, as shown in the example below.

Payload flattening no longer happens by default

This Action no longer flattens or stringifies payloads being sent to Workflow Builder by default.

Prior to updating: Payloads sent using a webhook trigger were flattened with a . delimiter and have values stringified before being sent.

Recommended change: If payload flattening is needed, use the payload-delimiter option. Inputs of Slack workflows should use an underscore _ as a delimiter to match expected inputs of Workflow Builder:

- name: Send GitHub Action data to a Slack workflow
  uses: slackapi/[email protected]
  with:
    payload-delimiter: "_"
    webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
    webhook-type: webhook-trigger

🎁 Enhancements

The webhook URL can be specified in webhook inputs

This Action can now set the webhook URL as a step input.

Prior to updating: The SLACK_WEBHOOK_URL environment variable set this value.

Recommended change: Optional. Use the webhook input value, as shown above, to set the webhook URL.

Technique 2: Slack API methods

This technique can now send to the Slack API methods and supports all token types!

⚠️ Breaking changes

The Slack API method now must be specified in inputs

This Action now requires that the Slack API method is specified in inputs.

Prior to updating: Messages would be posted using chat.postMessage or chat.update behind the scenes.

Recommend change: Use the method that matches the message being posted, or use a different method:

- name: Post to a Slack channel
  uses: slackapi/[email protected]
  with:
    method: chat.postMessage
    token: ${{ secrets.SLACK_BOT_TOKEN }}
    payload: |
      channel: ${{ secrets.SLACK_CHANNEL_ID }}
      text: "Greetings <@channel>!"

Note: Steps with update-ts should use chat.update as the method.

A token must be provided with other inputs

This Action expects a token as a step input value.

Prior to updating: Bot tokens were provided with the SLACK_BOT_TOKEN environment variable.

Recommended change: Provide the token scoped for the method as a step input, as shown above. The SLACK_TOKEN environment variable can also be used.

Inputs to the Slack API method must be provided in payloads

This Action now passes all provided values for payloads to the Slack API method.

Prior to updating: The channel-id and slack-message values were used.

Recommended change: Include the values sent to the Slack API method in the provided payload, as shown above.

Messages cannot be sent to multiple channels in one step

This Action can no longer send messages to multiple channels.

Prior to updating: Multiple channels could be provided to channel-id.

Recommended change: Update your GitHub workflow to repeat the same chat.postMessage step multiple times with different channel IDs.

Technique 3: Slack incoming webhook

⚠️ Breaking changes

The webhook type must be specified for incoming webhooks

This Action now requires setting the webhook-type as a step input value.

Prior to updating: The webhook type could be omitted to send to Workflow Builder.

Recommended change: Set the webhook-type value to incoming-webhook, as shown in the example below:

- name: Post a message in a channel
  uses: slackapi/[email protected]
  with:
    webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
    webhook-type: incoming-webhook
    payload: |
      text: "Greetings from this step!"

🎁 Enhancements

The webhook URL must be specified for incoming webhooks

This Action can now set the webhook URL as a step input.

Prior to updating: The SLACK_WEBHOOK_URL environment variable set this value.

Recommended change: Optional. Use the webhook input value, as shown above, to set the webhook URL.

Additional configurations

🎁 Enhancements

Steps can exit with an error after a failed Slack API call

This Action can now exit if the Slack API returns an erroring response.

Prior to updating: Errors due to invalid payloads were ignored.

Recommended change: If a failing response from the Slack API should cause a step to fail, the errors value should be set to true since it defaults to false:

- name: Attempt to inverse a message
  uses: slackapi/[email protected]
  with:
    errors: true
    method: chat.reverse
    token: ${{ secrets.SLACK_BOT_TOKEN }}
    payload: |
      "message": "palindrome"

Failed requests can be retried various amounts of times

This Action can now retry requests that failed due to rate limits.

Prior to updating: Rate limited requests were retried a fixed amount of times.

Recommended change: Set the retries option to a setting of choice:

- name: Attempt to inverse a message
  uses: slackapi/[email protected]
  with:
    method: chat.postMessage
    retries: rapid
    token: ${{ secrets.SLACK_BOT_TOKEN }}
    payload: |
      "message": "Good luck!"

Provided payloads can be flattened with a delimiter

This Action can now flatten and stringify payloads from any source.

Prior to updating: Payloads from the payload-file-path source were flattened with a period . delimiter by default.

Recommended change: Set the payload-delimiter option to an underscore _ to flatten and stringify nested payloads:

- name: Send GitHub Action data to a Slack workflow
  uses: slackapi/[email protected]
  with:
    payload-delimiter: "_"
    webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
    webhook-type: webhook-trigger

In the example above, data from the default GitHub event context and event payload are flattened before being sent with a webhook to Workflow Builder, matching the expected input shape of Workflow Builder.

Provided payloads can have templated variables replaced

This Action can now replace templated variables from any source.

Prior to updating: Templated variables were replaced by default in payloads from the payload-file-path source.

Recommended change: Set the payload-templated option to true to replace templated variables in provided payloads:

- name: Send custom JSON data to Slack workflow
  uses: slackapi/[email protected]
  with:
    payload-file-path: "./payload-slack-content.json"
    payload-templated: true
    webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
    webhook-type: webhook-trigger

Proxying HTTPS requests can be done within inputs

This Action can now set HTTPS proxies within the step inputs.

Prior to updating: The HTTPS_PROXY environment variable was recommended.

Recommended change: Set the proxy step input:

- name: Post to a Slack channel via a proxy
  uses: slackapi/[email protected]
  with:
    method: chat.postMessage
    proxy: "http://proxy.example.org:8080" # Change this to a custom value
    token: ${{ secrets.SLACK_BOT_TOKEN }}
    payload: |
      channel: ${{ secrets.SLACK_CHANNEL_ID }}
      text: "This message was sent through a proxy"

Expected outputs

The outputs from steps continues to return the following values, with changes noted below:

time: number The Unix epoch time that the step completed.
channel_id: string. The channel ID included in the response of some Slack API methods.
ts: string. The timestamp of the Slack event or message.
thread_ts: string. The timestamp of a parent Slack message with threaded replies.

⚠️ Breaking changes

The time value is now returned as the Unix epoch time

This Action now returns the Unix epoch time of when the step completed.

Prior to updating: The returned time value was formatted as a JavaScript date.

Recommenced change: Configure following steps to use time as an epoch offset.

🎁 Enhancements

An ok value is added to represent response success

This Action now returns ok to represent a successful send.

Prior to updating: Checking the time value or other outputs could be used to determine the status of some steps.

Recommended change: Configure steps that require certain successful responses of prior steps to check ok:

- name: Send a message into channel
  id: message
  uses: slackapi/[email protected]
  with:
    method: chat.postMessage
    token: ${{ secrets.SLACK_BOT_TOKEN }}
    payload: |
      channel: ${{ secrets.SLACK_CHANNEL_ID }}
      text: "Something is happening and is in action"
- name: Reply to that message with outputs
  if: ${{ steps.message.outputs.ok }}
  uses: slackapi/[email protected]
  with:
    method: chat.postMessage
    token: ${{ secrets.SLACK_BOT_TOKEN }}
    payload: |
      channel: ${{ secrets.SLACK_CHANNEL_ID }}
      text: "The previous step completed <!date^${{ steps.message.outputs.time }}^{date_num} at {time_secs}|just now>."
      thread_ts: "${{ steps.message.outputs.ts }}"

A response value is added with the response data

This Action now returns the JSON response value from Slack API requests.

Prior to change: Some response values were returned for conversation APIs.

Recommended change: Use the output response of one step as input to another for more complex workflows.

We're hoping the update goes well, but please do let us know if something seems off! 💌