Notify Slack Action

Send Github Actions workflow status notifications to Slack regarding failures, warnings or even success. You can read more about the action in our blog post.

Features

• Ability to control when to send notification
• Custom Notification Title, Message and Footer using template variables
• Mention Users and control when to mention them
• Mention Users Groups and control when to mention them
• Customize icons based on the action status

Example workflows

Minimal workflow

steps:
  - uses: ravsamhq/notify-slack-action@v2
    if: always()
    with:
      status: ${{ job.status }} # required
    env:
      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }} # required

Running a workflow only on the specified branch

To run the notifier for a specific branch, you can utilize the either github.ref_name for pushes or github.head_ref for pull requests. For example, if you want to run the notifier only on the origin/main branch for pushes the following would constrain the workflow to that branch:

steps:
  - name: Notify Slack Action
    uses: ravsamhq/notify-slack-action@2.3.0
    if: ${{ always() && github.ref_name == 'main' }}
    with:
      status: ${{ job.status }}
      notify_when: "failure"
      notification_title: "{workflow} is failing"
    env:
      SLACK_WEBHOOK_URL: ${{ secrets.ACTION_MONITORING_SLACK }}

Extended Example without User Mentions

steps:
  - uses: ravsamhq/notify-slack-action@v2
    if: always()
    with:
      status: ${{ job.status }}
      token: ${{ secrets.GITHUB_TOKEN }}
      notification_title: "{workflow} has {status_message}"
      message_format: "{emoji} *{workflow}* {status_message} in <{repo_url}|{repo}>"
      footer: "Linked Repo <{repo_url}|{repo}> | <{workflow_url}|View Workflow>"
    env:
      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

Extended Example with User Mentions

steps:
  - uses: ravsamhq/notify-slack-action@v2
    if: always()
    with:
      status: ${{ job.status }}
      notification_title: "{workflow} has {status_message}"
      message_format: "{emoji} *{workflow}* {status_message} in <{repo_url}|{repo}>"
      footer: "Linked Repo <{repo_url}|{repo}>"
      notify_when: "failure"
      mention_users: "U0160UUNH8S,U0080UUAA9N"
      mention_users_when: "failure,warnings"
    env:
      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

To get the Slack Member IDs, open the User profile you want to mention. Click More and Copy Member ID.

Extended Example with Users Groups Mentions

steps:
  - uses: ravsamhq/notify-slack-action@v2
    if: always()
    with:
      status: ${{ job.status }}
      notification_title: "{workflow} has {status_message}"
      message_format: "{emoji} *{workflow}* {status_message} in <{repo_url}|{repo}>"
      footer: "Linked Repo <{repo_url}|{repo}>"
      notify_when: "failure"
      mention_users: "U0160UUNH8S,U0080UUAA9N"
      mention_users_when: "failure,warnings"
      mention_groups: "SAZ94GDB8"
      mention_groups_when: "failure,warnings"
    env:
      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

To mention a channel, you can configure the mention_groups key like:

mention_groups: "SAZ94GDB8,!channel"

The following variables are available for formatting your own strings.

• {branch}
• {branch_url}
• {commit_url}
• {commit_sha}
• {emoji}
• {repo}
• {repo_url}
• {status_message}
• {run_url}
• {job}
• {workflow}
• {workflow_url}

You can use these to construct custom notification_title, message_format and footer.

In order to use {workflow_url}, specify the token input as token: ${{ secrets.GITHUB_TOKEN }}.

The above mentioned strings are available by default. However, you can use the following method to use any kind of data available in GitHub Actions:

1. Add the following step to get all the information related to your GitHub context

steps:
  - run: echo "${{ toJson(github) }}"

2. Then you can reference the github object properties:

github.event.head_commit.author.name
github.event.head_commit.message

as

steps:
  - uses: ravsamhq/notify-slack-action@v2
    if: always()
    with:
      ...
      message_format: '{emoji} ${{ github.event.head_commit.author.name }} ${{ github.event.head_commit.message }}'
    env:
      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

Inputs

status:
  description: Job Status
  required: true

token:
  description: Github Token for accessing workflow url
  required: false
  default: ""

notification_title:
  description: Specify on the notification message title
  required: false
  default: "New Github Action Run"

message_format:
  description: Specify on the notification message format
  required: false
  default: "{emoji} *{workflow}* {status_message} in <{repo_url}|{repo}@{branch}> on <{commit_url}|{commit_sha}>"

footer:
  description: Specify the footer of the message
  required: false
  default: "<{run_url}|View Run> | Developed by <https://www.ravsam.in|RavSam>"

notify_when:
  description: Specify on which events a slack notification is sent
  required: false
  default: "success,failure,cancelled,warnings,skipped"

mention_users:
  description: Specify the slack IDs of users you want to mention.
  required: false
  default: ""

mention_users_when:
  description: Specify on which events you want to mention the users
  required: false
  default: "success,failure,cancelled,warnings,skipped"

mention_groups:
  description: Specify the slack IDs of groups you want to mention
  required: false
  default: ""

mention_groups_when:
  description: Specify on which events you want to mention the groups
  required: false
  default: "success,failure,cancelled,warnings,skipped"

icon_success:
  description: Specify on icon to be used when event is success
  required: false
  default: ":heavy_check_mark:"

icon_failure:
  description: Specify on icon to be used when event is failure
  required: false
  default: ":x:"

icon_cancelled:
  description: Specify on icon to be used when event is cancelled
  required: false
  default: ":x:"

icon_warnings:
  description: Specify on icon to be used when event is warnings
  required: false
  default: ":large_orange_diamond:"

icon_skipped:
  description: Specify on icon to be used when event is skipped
  required: false
  default: ":fast_forward:"

Development

Follow these instructions to get the project up and running:

# clone the repo
git clone https://github.com/ravsamhq/notify-slack-action.git

# change directory
cd notify-slack-action

# install dependencies
npm install

Versioning

This project uses SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Ravgeet Dhillon

Contributors

• Ravgeet Dhillon
• Jirka Borovec
• Vlad Pronsky
• erezarnon

Special shoutout to Vlad Pronsky for porting the original Python based code to Typescript.

Extra

• We are open for issues and feature requests.
• In case you get stuck at somewhere, feel free to contact at our Mail.

© 2022 RavSam Web Solutions