https://github.com/freckle/slack-notify-action
https://github.com/freckle/slack-notify-action
ghvm-managed
Last synced: 5 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/freckle/slack-notify-action
- Owner: freckle
- Created: 2024-04-22T14:12:38.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2026-01-15T09:37:21.000Z (5 months ago)
- Last Synced: 2026-01-15T15:34:58.592Z (5 months ago)
- Topics: ghvm-managed
- Homepage:
- Size: 90.8 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Slack Notify
## Description
Minimal inputs action to notify Slack of Job status
## Features
1. Reasonable defaults, only one required input
1. Tidy message format, erring on unobtrusiveness
1. Default title and color based on workflow, job, and status
1. Includes commit details and URL to the run
1. Maps GitHub users to Slack users (requires configuration)
## Inputs
| name | description | required | default |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------- |
| `slack-webhook-url` |
Slack webhook url, typically a repository secret.
| `true` | `""` |
| `slack-channel` | Explicit channel for this notification. If omitted (the default), the channel configured in the webhook is used.
| `false` | `""` |
| `event-name` | A name for the event being notified about. If not given, the workflow and job id is used.
| `false` | `""` |
| `message` | Additional content to add to the message. Details about the commit that triggered the Job in which this step is run are always included.
| `false` | `""` |
| `commit-sha` | Commit SHA to fetch details for. Default is the PR head sha or github.sha if not in the context of a PR.
| `false` | `${{ github.event.pull_request.head.sha \|\| github.sha }}` |
| `slack-users` | A JSON object (as a string in the Yaml) mapping GitHub usernames to Slack User Ids (e.g. UXXXXXX). If present, the commit author is looked up in the map and the Slack user, if found, is at-mentioned in the notification details. If a Slack user is not found, an error is generated as a build annotation.
| `false` | `""` |
| `slack-users-file` | Relative path within the repository to read the slack-users JSON from a file. The file is read from the default branch via the API.
| `false` | `""` |
| `job-name` | An explicit job-name, in cases where github.job (the job.id) won't work such as matrix jobs.
| `false` | `""` |
| `job-status` | An explicit job-status, in cases where the status of the current job is not the desired status to notify about.
| `false` | `""` |
| `github-token` | | `false` | `${{ github.token }}` |
| `dry-run` | Don't actually notify (useful for testing)
| `false` | `false` |
## Usage
```yaml
- uses: freckle/slack-notify-action@v1
with:
slack-webhook-url:
# Slack webhook url, typically a repository secret.
#
# Required: true
# Default: ""
slack-channel:
# Explicit channel for this notification. If omitted (the default), the
# channel configured in the webhook is used.
#
# Required: false
# Default: ""
event-name:
# A name for the event being notified about. If not given, the
# workflow and job id is used.
#
# Required: false
# Default: ""
message:
# Additional content to add to the message. Details about the commit that
# triggered the Job in which this step is run are always included.
#
# Required: false
# Default: ""
commit-sha:
# Commit SHA to fetch details for. Default is the PR head sha or github.sha
# if not in the context of a PR.
#
# Required: false
# Default: ${{ github.event.pull_request.head.sha \|\| github.sha }}
slack-users:
# A JSON object (as a string in the Yaml) mapping GitHub usernames to Slack
# User Ids (e.g. UXXXXXX). If present, the commit author is looked up in the
# map and the Slack user, if found, is at-mentioned in the notification
# details. If a Slack user is not found, an error is generated as a build
# annotation.
#
# Required: false
# Default: ""
slack-users-file:
# Relative path within the repository to read the slack-users JSON from a
# file. The file is read from the default branch via the API.
#
# Required: false
# Default: ""
job-name:
# An explicit job-name, in cases where github.job (the job.id) won't work
# such as matrix jobs.
#
# Required: false
# Default: ""
job-status:
# An explicit job-status, in cases where the status of the current job is not
# the desired status to notify about.
#
# Required: false
# Default: ""
github-token:
#
# Required: false
# Default: ${{ github.token }}
dry-run:
# Don't actually notify (useful for testing)
#
# Required: false
# Default: false
```
## Job Name
In order to locate the URL to the Job in which we're running, we need to know
the Job _Name_. Within the action, GitHub exposes `github.job`, which is the Job
_Id_. These are usually the same, unless you've given an explicit `name` or are
running the Job in a matrix. If either of these are true, the action cannot
determine the Job URL and will error. Unfortunately, GitHub does not offer any
way for us to handle this, so you must provide the `job-name` input from the
outside:
```yaml
name: "My Cool Job"
steps:
- uses: freckle/slack-notify-action@v1
with:
slack-webhook: ${{ secrets.SLACK_WEBHOOK }}
job-name: "My Cool Job"
```
For matrices, as least you can build it dynamically:
```yaml
strategy:
matrix:
env:
- dev
- prod
steps:
- uses: freckle/slack-notify-action@v1
with:
slack-webhook: ${{ secrets.SLACK_WEBHOOK }}
job-name: ${{ github.job }} (${{ matrix.env }})
```
## Slack Users
If told the mapping from GitHub Username to Slack User Id, this action will
at-mention the author of the commit in which the Job is running:
```yaml
- uses: freckle/slack-notify-action@v1
with:
slack-webhook: ${{ secrets.SLACK_WEBHOOK }}
slack-users: |
{
"octocat": "UXXXXXX",
"pbrisbin": "UXXXXXX"
}
```
If this content gets too big, you can store it in the repository instead:
```yaml
- uses: freckle/slack-notify-action@v1
with
slack-webhook: ${{ secrets.SLACK_WEBHOOK }}
slack-users-file: .github/slack.json
```
The file is read from the default branch using the API (so no checkout is
required.)
## Release
TODO