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/[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 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/[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
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/[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."
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.
12 May 18, 2022
3 Oct 11, 2021
0 Feb 20, 2022
18 Jul 31, 2022
3 Aug 07, 2021
7 Jul 04, 2022
24 Dec 05, 2022
2 Dec 16, 2022
1 Dec 19, 2022
0 Feb 16, 2022
195 Jan 04, 2023
2 Feb 14, 2022
226 Jan 02, 2023
11 Oct 21, 2022
2 Dec 01, 2021
2 Aug 19, 2022
2 Nov 28, 2021
4 Jan 27, 2022
6 Dec 24, 2022
6 Jun 22, 2022