Slack - Github Action

A Github Action that sends custom Slack notifications by use of templates.

Examples of Some Templates

push1

steps1

Configuration

1. Create an Incoming Webhook in your Slack workspace. Copy the webhook URL, you'll need it in the next step.
2. Create a Github secret in the settings tab in a repository, or organization if you want it to be used across all repositories within an organization. Give it the name "SLACK_WEBHOOK_URL" and value as the webhook URL.

Usage

1. Add "SLACK_WEBHOOK_URL" as an env to every workflow file you want to use this action in.

   env:
     SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
   

2. Add this action as a step and make sure to replace x.y.z. with a valid release version:

   - name: Send Slack Notification
     uses: keithalpichi/slack-action@x.y.z
   

3. Add your desired inputs from the input section below to the step.

Github Action Inputs

Below are required inputs.

input	short description
template	The template ID that identifies the template to use for the Slack notification message. See the Templates section below for images and details of each template.

Below are inputs that are required or optional depending on the template you use.

input	short description
title	The title to display on the Slack notification message. If this is not provided, "Github Action" is used.
description	The description to display on the Slack notification message.
status	The status to report. Have Github report the job's status or provide your own.

Below are inputs that are optional and used to override the default configuration settings assigned to the Slack Incoming Webhook.

input	short description
channel	The channel or user to send the Slack message to.
username	The username of the message.
icon_emoji	Emoji to use as the icon for this message. Overrides icon_url. Find an appropriate emoji from this source.
icon_url	Public URL to an image to use as the icon for this message

template

(required)

The template ID that identifies the template to use for the Slack notification message. You can use the following templates:

• plain1- a template for plain messages that displays a custom description.
• plain2- a template for plain messages that displays the link to the current Github Action run.
• push1- a template for a message with push event details such as git commit hash, run ID & #, branch, status and more provided in a two-column table.
• steps1- a template for a message that summarizes the statuses of all the steps in the job. Each summary includes an emoji, the step identifier, and the status of the step.

See the Templates section below for images and details of each template.

Example usage

- name: Send Slack Notification
  uses: keithalpichi/slack-action@x.y.z
  with:
    template: plain2

title

The title to display on the Slack notification message. If this is not provided, "Github Action" is used.

Example usage

- name: Send Slack Notification
  uses: keithalpichi/slack-action@x.y.z
  with:
    template: plain2
    title: Success

description

The description to display on the Slack notification message.

Example usage

- name: Send Slack Notification
  uses: keithalpichi/slack-action@x.y.z
  with:
    template: plain1
    description: Everything looks good!

status

The current status of the job to use within the template. Usage of this input depends on the template input provided. If you'd like for Github to report the current status of the job use ${{ job.status }}. Possible status values reported by Github are success, failure, or cancelled. You may also choose to provide any string value.

Example usage

Using the job.status context:

- name: Send Slack Notification
  uses: keithalpichi/slack-action@x.y.z
  with:
    status: ${{ job.status }}
    template: plain2

Providing a custom status:

- name: Send Slack Notification
  uses: keithalpichi/slack-action@x.y.z
  with:
    status: all green
    template: plain2

channel

Overrides the default channel or user to send the Slack message to.

• If a channel is provided it must be a valid channel that starts with '#'
• If a user is provided it must be a valid user that starts with '@'

Example usage

- name: Send Slack Notification
  uses: keithalpichi/slack-action@x.y.z
  with:
    template: plain1
    channel: #pets

- name: Send Slack Notification
  uses: keithalpichi/slack-action@x.y.z
  with:
    template: plain1
    channel: @octocat

username

Overrides the default username of the message. This is the name specified as the sender of the message.

Example usage

- name: Send Slack Notification
  uses: keithalpichi/slack-action@x.y.z
  with:
    template: plain2
    username: Al

icon_emoji

Overrides the default emoji to use as the icon for this message. Overrides icon_url if they're both provided. Find an appropriate emoji from this source. Ensure the emoji starts and ends with a colon.

Example usage

- name: Send Slack Notification
  uses: keithalpichi/slack-action@x.y.z
  with:
    template: plain2
    icon_emoji: ":fire:"

icon_url

Overrides the default public URL to an image to use as the icon for this message. This will be overridden by icon_emoji if they're both provided.

Example usage

- name: Send Slack Notification
  uses: keithalpichi/slack-action@x.y.z
  with:
    template: plain2
    icon_url: https://octodex.github.com/images/original.png

Examples

Using Github Action status check functions to conditionally run this Github Action

This is useful if you want to run this Github Action only when a certain status exists:

steps:
  ...
  - name: Always notify Slack no matter what happens
    if: ${{ always() }}

steps:
  ...
  - name: Only notify Slack when it is successful
    if: ${{ success() }}

steps:
  ...
  - name: Only notify Slack when there is a failure
    if: ${{ failure() }}

Templates

plain1

A message with a text description and default title. This template uses the following inputs:

• description (required)- the description in the message
• title - if provided overrides the default title "Github Action"
• channel- if provided overrides the default channel assigned to the Slack Incoming Webhook

with:
  template: plain1
  description: We're all green!

plain2

A message with a link to the Github Action run and default title. This template uses the following inputs:

• title - if provided overrides the default title "Github Action"
• channel- if provided overrides the default channel assigned to the Slack Incoming Webhook

with:
  template: plain2

with:
  title: ${{ job.status }}
  template: plain2

A message with a link to the Github Action run and job status as the title.

with:
  title: We're all green!
  template: plain2

A message with a link to the Github Action run and a custom title as the title.

push1

this template can only be used for "push" events

A message with push event details provided in a two-column table. The link to the workflow run is provided in the "Run Number" cell. This template uses the following inputs:

• status (required)- the status to put into the "Status" cell (see image below)
• title - if provided, overrides the default title "Github Action"
• description- if provided, inserts the description below the title
• channel- if provided, overrides the default channel assigned to the Slack Incoming Webhook

with:
  template: push1
  description: optional description
  status: ${{ job.status }}

steps1

A message that summarizes the statuses of all the steps in the job. Each summary includes an emoji, the step identifier, and the status of the step. This template uses the following inputs:

• steps (required)- the steps Github Action context. It's as simple as providing ${{ toJSON(steps) }} to this step.
• title - if provided, overrides the default title "Github Action"
• description- if provided, inserts the description below the title
• channel- if provided, overrides the default channel assigned to the Slack Incoming Webhook

with:
  template: steps1
  description: optional description
  title: optional Title
  status: ${{ toJSON(steps) }}