slack-templates
Send Informative, Concise Slack Notifications With Minimal Effort
- slack-templates
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_requestevent: <workflow> <result> for <PR #> from <branch> on <repository> by <username>.pushevent:- merge of pull request: <workflow> <result> for merge of <PR #> from <branch> on <repository> by <username>.
- direct push of branch: <workflow> <result> for push of <sha> to <branch> on <repository> by <username>.
"reviewers":requestor != requestee: <requestor> requests review from <reviewers> of <PR #> from <branch> on <repository>.requestor == requestee: <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 themessageparameter.
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/slack-templates@0
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 theresults.
The result of the entire workflow is the highest ranking of all results given. The ranking is as follows:
- failure
- cancelled
- success
- 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/slack-templates@0
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
resultsfor use as a Bash command line argument.
- name: Detect third-party network outage.
id: network
run: |
...
echo "::set-output name=outage::$OUTAGE"
shell: bash
- name: Send Slack notification with custom result.
if: always() && steps.network.outputs.outage == 'true'
uses: ScribeMD/slack-templates@0
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/slack-template@0
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/slack-templates@0
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/slack-templates@0
with:
bot-token: ${{ secrets.SLACK_TEMPLATES_BOT_TOKEN }}
channel-id: ${{ secrets.SLACK_TEMPLATES_CHANNEL_ID }}
message: "${{ github.actor }} requests approval to run workflow."
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 parameterbot-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.
Contributing
Please refer to CONTRIBUTING.md.
Changelog
Please refer to CHANGELOG.md.
1 Jan 11, 2022
1 Jan 14, 2022
2 Apr 25, 2022
8 May 18, 2022
6 Nov 27, 2022
25 Aug 16, 2022
48 Oct 31, 2022
8 Jan 30, 2022
7.2k Jan 7, 2023
1 Jul 22, 2022
2 Jan 20, 2022
1.6k Dec 13, 2022
149 Jun 30, 2022
26 May 28, 2022
3.5k Jan 2, 2023
14 Nov 19, 2021
4 Feb 15, 2022
7 Jan 6, 2022
3 Jun 22, 2021