Slack GitHub Action

The Slack GitHub Action provides four distinct methods for interacting with Slack within your GitHub workflows:

1. Workflow Builder Webhooks: Send data to a Slack workflow via a webhook.
2. Slack API Methods: Send data using specific Slack API methods. This requires a secret token with the appropriate scopes.
3. Incoming Webhooks: Send data as a message using a Slack incoming webhook URL.
4. Slack CLI Commands: Execute Slack CLI commands directly.

The Slack GitHub Action allows you to integrate Slack functionality into your GitHub workflows. You can use it to:

• Start a Slack Workflow: Send data via a webhook to trigger a workflow in Slack Workflow Builder.
• Call Slack API Methods: Send data using a specific Slack API method and a secret token (requires appropriate scopes).
• Send Messages via Incoming Webhooks: Send data as a message using a Slack incoming webhook URL.
• Run Slack CLI Commands: Execute Slack CLI commands using a service token.

For detailed implementation guides, refer to the official documentation at docs.slack.dev/tools/slack-github-action.

The Slack API method technique allows you to call any Slack API method directly from a GitHub Action. This requires a Slack token (such as a bot token or user token) to authenticate the requests.

This technique is useful when you need to perform complex or specific actions that are not covered by the action's built-in high-level features, such as chaining multiple API calls together.

Slack Workflow Builder requires payload variables to be flattened and stringified. Use the payload-delimiter option to flatten nested fields in your payload. For example, a nested field user: { name: 'Alice' } with a delimiter of _ becomes user_name: 'Alice'. This implementation is based on the flat npm package.

- name: Flatten the default GitHub payload
  uses: slackapi/slack-github-action@v4.0.0
  with:
    payload-delimiter: "_"
    webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
    webhook-type: webhook-trigger

Technique 1 uses Slack Workflow Builder to receive data from GitHub Actions via a webhook trigger. This allows you to trigger complex, multi-step Slack workflows (like opening forms, sending messages, or updating channel topics) by sending a payload from your GitHub workflow to a Slack webhook URL.

Note: This technique requires a Slack paid plan.

When using the Slack GitHub Action, you can provide the data to be sent to Slack from one of two sources:

1. The default GitHub event context: The action can automatically use the payload matching the current GitHub event (e.g., push, pull_request).
2. A custom payload: You can provide a custom payload by defining variables within your GitHub Action step.

Note that while these two sourcing methods are available for all techniques, certain techniques may impose specific constraints or requirements on the inputs provided.

You can enable verbose output in two ways:

1. Automatically: When a workflow is re-run with Enable debug logging enabled in GitHub, the action automatically appends --verbose to the command.
2. Manually: Include --verbose directly in your command input string.

- uses: slackapi/slack-github-action/cli@v4.0.0
  with:
    command: "deploy --app ${{ vars.SLACK_APP_ID }} --verbose"
    token: ${{ secrets.SLACK_SERVICE_TOKEN }}

It is recommended to use the latest version of the Slack GitHub Action to ensure you have the most recent updates and fixes.

When upgrading between major versions (e.g., from @v1 to @v2, @v3, or @v4), consult the migration guides available in the release notes to handle breaking changes.

To use this Action to post messages to a Slack channel or direct message, follow these setup steps:

1. Create a Slack app: Go to api.slack.com/apps/new.
2. Add Scopes: Under OAuth & Permissions, add the incoming-webhook bot scope.
3. Install App: Install the app to your workspace and select a destination channel.
4. Generate Webhook: Go to the Incoming Webhooks page and create a new webhook.
5. Store Secret: Add the generated URL (e.g., https://hooks.slack.com/services/T.../B.../...) as a GitHub repository secret named SLACK_WEBHOOK_URL.
6. Configure Workflow: Add the Action as a step in your GitHub workflow and provide a payload.

To use this technique, you must have a Slack paid plan to access Workflow Builder.

1. Create a Slack workflow: In Slack, create a workflow that starts from a webhook.
2. Store the URL: Copy the generated webhook URL (e.g., https://hooks.slack.com/triggers/T0123456789/...) and add it to your GitHub repository secrets as SLACK_WEBHOOK_URL.
3. Configure Workflow: Add the slackapi/slack-github-action@v4.0.0 step to your GitHub workflow and provide an input payload.
4. Map Variables: In Slack Workflow Builder, configure your steps to use the payload variables sent from the action.

To post a message using an incoming webhook, add a step to your GitHub workflow using slackapi/slack-github-action@v4.0.0. You must specify webhook-type: incoming-webhook and provide a payload. The payload can include text (using mrkdwn formatting) or blocks (using Slack's Block Kit).

- name: Post a message in a channel
  uses: slackapi/slack-github-action@v4.0.0
  with:
    webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
    webhook-type: incoming-webhook
    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 }}"