action-notify-slack

A GitHub Action for sending notifications as Slack Attachments

Features

• Easily notify using a default template
• Replace default template with your own
• Add more fields on top of default/custom template
• Update previously sent messages
• Update single notification across multiple jobs in a workflow
• Send multiple Attachments
• Incredibly fast! About 2MB docker image

Manual

1. Create a Secret containing a Slack Token (manual).
2. Create a Secret containing a Slack Channel ID (manual).
3. Add action-notify-slack to your workflow:

    - name: Notification
      uses: docker://reasonsoftware/action-notify-slack:v1
      env:
        TOKEN: ${{ secrets.SLACK_TOKEN }}
        CHANNEL: ${{ secrets.SLACK_CHANNEL }}
        STATUS: started

Configuration

Configure this action via environmental variables:

• Required settings:
  • TOKEN: Slack Token
  • CHANNEL: Slack Channel
• Optional settings:
  • STATUS: defines a color of an attachment and text under Status field. Choose one of the following:
    • running/started/building/initializing: Yellow 🟨
    • deploying/uploading/publishing/creating: Orange 🟧
    • finished/succeeded/passed/built/released: Green 🟩
    • failed/aborted/canceled/terminated: Red 🟥
    • Anything Else: Gray ⬜
  • TIMESTAMP: update previously sent message by providing an output of a previous step
  • ATTACHMENTS_FILE: provide a path to JSON file containing a valid Slack Attachment to override a message template with your own (STATUS and SEPARATOR will be ignored)
  • SEPARATOR: argument separator for additional fields (default ==)
  • TIMESTAMP_FILE: a path to a file (directory and file will be created if not exist) which will contain a timestamp. Used as a buffer on complex flows that constantly update the same message (If used in multi-job workflow, you will have to collect that file as an artifact and extract it in another job)
  • FAIL: failure trap which will tweak the message to be failed on value "true". Useful in a mid flow notification with parameter: FAIL: "${{ failure() }}" (enables to send a finished or failed message in a single step)

Examples

ℹ️ Additional Fields

You may add additional fields to a default message template via arguments

• Default separator == may be changed by setting an environmental variable SEPARATOR with a custom value
• Arguments are expected to be divided by new line \n
• Field Name or Values should be enclosed in " if they contain whitespace

    - name: Notification
      uses: docker://reasonsoftware/action-notify-slack:v1
      env:
        TOKEN: ${{ secrets.SLACK_TOKEN }}
        CHANNEL: ${{ secrets.SLACK_CHANNEL }}
        STATUS: finished
      with:
        args: |
          "Download URL"==<https://my-website.com/file.exe|file>
          Version==v3.1.0

ℹ️ Custom Message

Create a JSON file with Slack attachments and provide a path as an environmental variable. For instance:

• Use another action to create attachments with your information dynamically
• Use a shell to create attachments dynamically
• Store it somewhere and fetch the file during the execution with curl or wget
• Commit a base skeleton to the repository and modify it in a dedicated step

    - name: Notify Slack
      uses: docker://reasonsoftware/action-notify-slack:v1
      env:
        TOKEN: ${{ secrets.SLACK_TOKEN }}
        CHANNEL: ${{ secrets.SLACK_CHANNEL }}
        ATTACHMENTS_FILE: attachments.json

⚠️ Remarks

• Provide either a single attachment ({}) or a list of attachments ([]) in a single JSON file
• Design your message here
• Remember to provide only the attachments and not a whole message

ℹ️ Update Message

• Add an id field to a first notification in a workflow
• Reference outputs.timestamp of previously set id as a TIMESTAMP env.var in the next notification
  • You may chain more notification steps using the same technique. Just keep adding id's 😉

    - name: Notify
      id: notify
      uses: docker://reasonsoftware/action-notify-slack:v1
      env:
        TOKEN: ${{ secrets.SLACK_TOKEN }}
        CHANNEL: ${{ secrets.SLACK_CHANNEL }}
        START: building

    - name: Update Notification
      uses: docker://reasonsoftware/action-notify-slack:v1
      env:
        TOKEN: ${{ secrets.SLACK_TOKEN }}
        CHANNEL: ${{ secrets.SLACK_CHANNEL }}
        STATUS: released
        TIMESTAMP: ${{steps.notify.outputs.timestamp}}
      with:
        args: |
          Download==<https://my-website.com/file.exe|file>
          Version==v3.1.0

Timestamp File Buffer

• Add an id to your first notification in a workflow
• Reference outputs.timestamp of previously set id as a TIMESTAMP env.var in the next notification
  • You may chain more notification steps using the same technique. Just keep adding id's 😉

jobs:
  ci:
    name: build
    runs-on: ubuntu-latest
    steps:
      - name: Notification
        uses: docker://reasonsoftware/action-notify-slack:v1
        env:
          TOKEN: ${{ secrets.SLACK_TOKEN }}
          CHANNEL: ${{ secrets.SLACK_CHANNEL }}
          STATUS: started
          TIMESTAMP_FILE: .github/notify.ts

      - name: Checkout
        uses: actions/checkout@v2
      
      - name: Build
        run: docker build --tag=org/proj:tag .
      
      - name: Notification
        uses: docker://reasonsoftware/action-notify-slack:v1
        env:
          TOKEN: ${{ secrets.SLACK_TOKEN }}
          CHANNEL: ${{ secrets.SLACK_CHANNEL }}
          STATUS: publishing
          TIMESTAMP_FILE: .github/notify.ts
      
      - name: Push
        run: docker push org/proj:tag

      - uses: actions/upload-artifact@v2
        with:
          name: timestamp
          path: .github/notify.ts

      - name: Notification
        if: ${{ failure() }}
        uses: docker://reasonsoftware/action-notify-slack:v1
        env:
          TOKEN: ${{ secrets.SLACK_TOKEN }}
          CHANNEL: ${{ secrets.SLACK_CHANNEL }}
          STATUS: failed
          TIMESTAMP_FILE: .github/notify.ts

  cd:
    name: deploy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v2
        with:
          name: timestamp
          path: .github/notify.ts

      - name: Notification
        uses: docker://reasonsoftware/action-notify-slack:v1
        env:
          TOKEN: ${{ secrets.SLACK_TOKEN }}
          CHANNEL: ${{ secrets.SLACK_CHANNEL }}
          STATUS: deploying
          TIMESTAMP_FILE: .github/notify.ts
      
      - name: Deploy
        run: helm upgrade --install application repository/application
      
      - name: Notification
        uses: docker://reasonsoftware/action-notify-slack:v1
        env:
          TOKEN: ${{ secrets.SLACK_TOKEN }}
          CHANNEL: ${{ secrets.SLACK_CHANNEL }}
          STATUS: finished
          FAIL: ${{ failure() }}
          TIMESTAMP_FILE: .github/notify.ts

Notes

• This action is automatically built at Docker Hub, and tagged with latest / v1 / v1.2 / v1.2.3 allowing to lock against a certain version It's recommended to lock against a major version, for example v1
• Docker image is published both to Docker Hub and GitHub Packages. If you don't want to rely on Docker Hub but still want to use the dockerized action, you may switch from uses: docker://reasonsoftware/action-notify-slack:v1 to uses: docker://docker.pkg.github.com/reasonsoftware/action-notify-slack/action-notify-slack:v1

License

Apache-2.0 © 2021 Reason Cybersecurity Ltd.