slack-templates

Send Informative, Concise Slack Notifications With Minimal Effort

• slack-templates
  • Slack Integration
  • Available Templates
  • Usage
    • Report the status of the current job
    • Summarize the results of an entire workflow
    • Report a custom result
    • Notify reviewers of a pull request
    • Notify assignee of a pull request
    • Send a custom notification
  • Inputs
    • Required
    • Optional
  • Relation to slack-send
  • Bug Reports
  • Permissions
  • Changelog

Slack Integration

• Create a custom Slack app with the chat:write scope.
• Install the app to your workspace, and copy the provided OAuth access token.
• Create a GitHub secret to store the bot token.
• Invite your bot to the desired channel.
• Secondary-click on the channel, and select “Copy link.”
• Create a GitHub secret to store the final portion of the path. The channel ID is neither the name of the channel nor the URL.

Available Templates

The template parameter controls the structure of the Slack notification. Here are all currently supported templates:

• result:
  • pull_request event: <workflow> <result> for <PR #> from <branch> on <repository> by <username>.
  • push event:
    • merge of pull request: <workflow> <result> for merge of <PR #> to <branch> on <repository> by <username>.
    • direct push of branch: <workflow> <result> for push of <sha> to <branch> on <repository> by <username>.
• reviewers:
  • requester != reviewer: <requester> requests review from <reviewers> of <PR #> from <branch> on <repository>.
  • requester == reviewer: <username> self-requests review of <PR #> from <branch> on <repository>.
• assignee:
  • assignor != assignee: <assignor> assigned <assignee> <PR #> from <branch> on <repository>.
  • assignor == assignee: <username> self-assigned <PR #> from <branch> on <repository>.
• custom: Pass your custom message via the message parameter.

All usernames refer to GitHub usernames. Users with differing Slack and GitHub usernames may wish to register their GitHub username for Slack keyword notifications. Workflow names, pull request numbers, commit shas, branches, and repositories all link to the pertinent GitHub page. If you would like to see a template added, please open an issue or better still a pull request.

Reliably determining the pull request associated with a push event requires read permissions on the contents scope. Even the restrictive defaults grant this permission. If permissions are granted explicitly and contents: read is excluded, the commit sha will be reported instead of the pull request number, because merges will be indistinguishable from direct pushes.

Usage

Report the status of the current job

• Add the following step to the bottom of the job:

  - name: Send Slack notification with job status.
    if: always()
    uses: ScribeMD/[email protected]
    with:
      bot-token: ${{ secrets.SLACK_TEMPLATES_BOT_TOKEN }}
      channel-id: ${{ secrets.SLACK_TEMPLATES_CHANNEL_ID }}
      template: result

Summarize the results of an entire workflow

• Create a new job at the end of the workflow that depends on (a.k.a., needs) all other jobs but always runs.
• Pass "${{ join(needs.*.result, ' ') }}" as the results.

The result of the entire workflow is the highest ranking of all results given. The ranking is as follows:

1. failure
2. cancelled
3. success
4. skipped

name: My Workflow
on:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main
jobs:
  job1: ...
  job2: ...
  job3: ...
  notify:
    if: always()
    needs:
      - job1
      - job2
      - job3
    runs-on: ubuntu-latest
    steps:
      - name: Send Slack notification with workflow result.
        uses: ScribeMD/[email protected]
        with:
          bot-token: ${{ secrets.SLACK_TEMPLATES_BOT_TOKEN }}
          channel-id: ${{ secrets.SLACK_TEMPLATES_CHANNEL_ID }}
          template: result
          results: "${{ join(needs.*.result, ' ') }}"

Report a custom result

• Determine what result to send in preceding steps.
• Report the result at the bottom of the job as before.
• Take care to quote results for use as a Bash command line argument.

- name: Detect third-party network outage.
  id: network
  run: |
    ...
    echo "OUTAGE=$OUTAGE" >>"$GITHUB_OUTPUT"
  shell: bash
- name: Send Slack notification with custom result.
  if: always() && steps.network.outputs.OUTAGE == 'true'
  uses: ScribeMD/[email protected]
  with:
    bot-token: ${{ secrets.SLACK_TEMPLATES_BOT_TOKEN }}
    channel-id: ${{ secrets.SLACK_TEMPLATES_CHANNEL_ID }}
    template: result
    results: '"failure caused by third-party network outage"'

Notify reviewers of a pull request

name: Notify Reviewers
on:
  pull_request:
    types:
      - review_requested
jobs:
  notify-reviewers:
    runs-on: ubuntu-latest
    steps:
      - name: Send Slack notification requesting code review.
        uses: ScribeMD/[email protected]
        with:
          bot-token: ${{ secrets.SLACK_TEMPLATES_BOT_TOKEN }}
          channel-id: ${{ secrets.SLACK_TEMPLATES_CHANNEL_ID }}
          template: reviewers

Notify assignee of a pull request

name: Notify Assignee
on:
  pull_request:
    types:
      - assigned
jobs:
  notify-assignee:
    runs-on: ubuntu-latest
    steps:
      - name: Send Slack notification assigning pull request.
        uses: ScribeMD/[email protected]
        with:
          bot-token: ${{ secrets.SLACK_TEMPLATES_BOT_TOKEN }}
          channel-id: ${{ secrets.SLACK_TEMPLATES_CHANNEL_ID }}
          template: assignee

Send a custom notification

- name: Send custom Slack notification.
  if: always()
  uses: ScribeMD/[email protected]
  with:
    bot-token: ${{ secrets.SLACK_TEMPLATES_BOT_TOKEN }}
    channel-id: ${{ secrets.SLACK_TEMPLATES_CHANNEL_ID }}
    message: "${{ github.actor }} requests approval to run workflow."

Inputs

Required

bot-token

The Slack API bot token for your custom app with chat:write scope.

channel-id

The ID of a Slack channel to send notifications to. Your bot should be a member. Secondary-click on the channel in Slack, and select Copy link to copy a URL containing the channel ID.

Optional

template

default: custom

The type of Slack notification to send:

• assignee
• custom (requires message)
• reviewers
• result

results (template: result only)

default: ${{ job.status }}

The job results to report via Slack. To report the result of an entire workflow, use this action from a final notify job that depends on (a.k.a., needs) all other jobs. Then, pass join(needs.*.result, ' '). The highest ranking result will be reported:

1. failure
2. cancelled
3. success
4. skipped

Alternatively, a custom result may be passed provided that it is quoted for use as a Bash command line argument.

message (template: custom only)

default: Pass message or template to slack-templates.

A custom Slack message to send.

Relation to slack-send

This action wraps slack-send, its only runtime dependency, inheriting slack-send's support for all GitHub-hosted runners. There are three principal differences between these actions:

• slack-templates offers some default messages; slack-send presently does not.
• slack-send supports Slack's Workflow Builder (unavailable on free Slack plan) in addition to Slack apps. slack-templates only supports Slack apps.
• slack-send accepts the bot token as environment variable SLACK_BOT_TOKEN. slack-templates accepts it as the input parameter bot-token.

Bug Reports

If you are not receiving notifications, please review the Slack Integration section and then file a bug report containing the GitHub Action's logs if that doesn't resolve your issue. If you are receiving nondescript Slack notifications, please file a bug report with the notification you received taking care to preserve the links.

Permissions

The contents:read and pull-requests:read permissions are required in private repositories to determine the pull request associated with a push event since the push event itself doesn't contain this information.

Changelog

Please refer to CHANGELOG.md.