Getting Started with SMS Notifications using Africas Talking and GitHub Actions Part 3 - Error Notifications

This is part trois (3) in the Africas Talking and GitHub Actions series.

Find the other parts here:

1. Getting Started with SMS Notifications using Africas Talking and GitHub Actions Part 1

2. Getting Started with SMS Notifications using Africas Talking and GitHub Actions Part 2

Introduction

This is the third and final part of the Africas Talking and GitHub Actions series. In this part, we will be looking at how to send error notifications from our GitHub Actions workflow.

Reasons for Error Notifications

Let's look at why you would want to implement this:

• This is critical as it will help us know when our workflow fails and why it failed.

• It allows us to work on the issue as soon as possible.

• Frees up time to work on other things as you don't have to keep checking the workflow status.

• Allows monitoring of multiple workflows at the same time.

• Allows you to monitor workflows from multiple repositories at the same time.

Prerequisites

The prerequisites are similar to the previous parts. You will need:

1. An Africas Talking account.

2. A GitHub account with a repository (Alternatively create a new repo).

The diagram below shows a high-level overview of the workflow(s) we will be creating:

Getting Started 🤩

Steps 🚶

The steps below assume you have a GitHub account and a repository. If you don’t have a repository, you can create one by following the steps here. Once you have a repository, follow the steps below to get started.

• Get Africas Talking API keys 🔑:

1. Sign up on AfricasTalking.com

2. Get your username and API key from the SMS dashboard. Note you will be prompted for your password. Once the key is created and displayed copy and paste it elsewhere as they usually create a new one each time.

• Add secrets to GitHub repository(We will use these secrets in our workflow):

1. In your repo, go to Settings > Secrets > Actions

2. Add a secret AT_USERNAME with your username.

3. Add a secret AT_API_KEY with your API key.

4. Add a secret toPhoneNumber with the phone number you want to send the SMS to. (Format: +2547XXXXXXXX)

Once you have added the secrets, your secrets page should look like this:

Implementing error notifications

In parts one and two, we created a workflow that sends an SMS when a new commit is pushed to the repository. In this part, we will be looking at how to send an SMS when the workflow fails. This is a great way to automate error notifications and save time.

Again there a two main methods of implementing this:

1. Creating a new workflow.

2. Adding the error notification to the existing workflow.

Depending on the method you choose and the use case, the implementation will vary. We will look at both methods.

Creating a new workflow

This method is useful if you want to monitor multiple workflows from multiple repositories. It is also useful if you want to monitor a specific workflow from a specific repository.

To create a new workflow, follow the steps below:

1. In your repository, go to Actions > New workflow > Set up a workflow yourself

2. Name your workflow. For example, error-notification.yml

3. Copy and paste the code below into the editor:

name: Error Notification


on:
  workflow_run:
    workflows: ["<WORKFLOW_NAME>"] # Replace <WORKFLOW_NAME> with the name of the workflow you want to monitor. If you want to monitor all workflows, remove this line. If you want to monitor multiple workflows, add them separated by a comma. For example: ["<WORKFLOW_NAME>", "<WORKFLOW_NAME>"]
    branches: [dev, main]
    types:
      - completed

  workflow_dispatch:

jobs:

 build:
  runs-on: ubuntu-latest

  steps:
  - uses: actions/checkout@v4

  - name: SMS Notification
    if: ${{ github.event.workflow_run.conclusion == 'failure' || github.event.workflow_run.conclusion == 'cancelled' }}
    uses: alphaolomi/actions-africastalking@main
    with:
      fromPhoneNumber: 'INFO'   # or  ${{ secrets.fromPhoneNumber }}
      toPhoneNumber: ${{ secrets.toPhoneNumber }}
      message: ${{ github.event_name }} on ${{ github.repository }} by ${{ github.actor }} has ${{github.event.workflow_run.conclusion}}. Check it out at ${{ github.event.workflow_run.url }}
    env:
      AT_API_KEY: ${{ secrets.AT_API_KEY }}
      AT_USERNAME: ${{ secrets.AT_USERNAME }}

1. Replace <WORKFLOW_NAME> with the name of the workflow you want to monitor. If you want to monitor all workflows, remove line 7. If you want to monitor multiple workflows, add them separated by a comma. For example: ["<WORKFLOW_NAME>", "<WORKFLOW_NAME>"]

2. Replace fromPhoneNumber with the phone number you want to send the SMS from. You can also use a secret. For example: ${{ secrets.fromPhoneNumber }}

3. Replace toPhoneNumber with the phone number you want to send the SMS to. You can also use a secret. For example: ${{ secrets.toPhoneNumber }}

4. Replace message with the message you want to send. You can also use a secret. For example: ${{ github.event_name }} on ${{ github.repository }} by ${{ github.actor }} has ${{github.event.workflow_run.conclusion}}. Check it out at ${{ github.event.workflow_run.url }}. This will send a message with the event name, repository name, actor, workflow status and workflow URL.

The key to this workflow is the if statement on line 23. This statement checks if the workflow status is failure or cancelled. If it is, it sends the SMS. If not, it does nothing. This is useful as it allows us to monitor the workflow status and only send the SMS when the workflow fails.

This is replicated across the different versions/iterations of this workflow.

Once you have done this, your workflow should look like this:

Adding the error notification to the existing workflow

This method is useful if you want to monitor a specific workflow from a specific repository. It is also useful if you want to monitor multiple workflows from a specific repository. To add the error notification to the existing workflow, follow the steps below:

1. In your repository, go to Actions > Your workflow > Edit

2. Copy and paste the code below into the editor:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - name: SMS Notification
      if: ${{ github.event_name == 'push' && github.event.workflow_run.conclusion == 'failure' || github.event.workflow_run.conclusion == 'cancelled' }}
      uses: alphaolomi/actions-africastalking@main
      with:
        fromPhoneNumber: 'INFO'   # or  ${{ secrets.fromPhoneNumber }}
        toPhoneNumber: ${{ secrets.toPhoneNumber }}
        message: ${{ github.event_name }} on ${{ github.repository }} by ${{ github.actor }} has ${{github.event.workflow_run.conclusion}}. Check it out at ${{ github.event.workflow_run.url }}
      env:
        AT_API_KEY: ${{ secrets.AT_API_KEY }}
        AT_USERNAME: ${{ secrets.AT_USERNAME }}

1. Replace fromPhoneNumber with the phone number you want to send the SMS from. You can also use a secret. For example: ${{ secrets.fromPhoneNumber }}

2. Replace toPhoneNumber with the phone number you want to send the SMS to. You can also use a secret. For example: ${{ secrets.toPhoneNumber }}

3. Replace message with the message you want to send. You can also use a secret. For example: ${{ github.event_name }} on ${{ github.repository }} by ${{ github.actor }} has ${{github.event.workflow_run.conclusion}}. Check it out at ${{ github.event.workflow_run.url }}. This will send a message with the event name, repository name, actor, workflow status and workflow URL.

4. Click on Start commit > Commit changes

5. Click on Actions > Your workflow > Run workflow

6. Click on Run workflow

To test whether your workflow is working, you can trigger a workflow failure by adding an error to your code. For example, add an error to your code and push it to the repository. You should receive an SMS with the error message.

Using an SDK to send the SMS

In the previous parts, we used the actions-africastalking action to send the SMS. This action uses the Africas Talking API to send the SMS. You can also use the Africas Talking SDK to send the SMS.Here I'll provide a demo using the Africas Talking Python SDK. However, you can use any SDK you want. Adjust the code to suit your use case.

To do this, follow the steps below:

1. In your repository, go to Actions > Your workflow > Edit

2. Copy and paste the code below into the editor:

name: Error Notification

on:
  workflow_run:
    workflows: ["<WORKFLOW_NAME>"] # Replace <WORKFLOW_NAME> with the name of the workflow you want to monitor. If you want to monitor all workflows, remove this line. If you want to monitor multiple workflows, add them separated by a comma. For example: ["<WORKFLOW_NAME>", "<WORKFLOW_NAME>"]
    branches: [dev, main]
    types:
      - completed

  workflow_dispatch:

jobs:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

  - name: Install Africa's Talking SDK
         run: pip install africastalking

    - name: SMS Notification
      if: ${{ github.event_name == 'push' && github.event.workflow_run.conclusion == 'failure' || github.event.workflow_run.conclusion == 'cancelled' }}
    env:
      AT_API_KEY: ${{ secrets.AT_API_KEY }}
      AT_USERNAME: ${{ secrets.AT_USERNAME }}
      toPhoneNumber: ${{ secrets.toPhoneNumber }} # Replace with your phone number
    run: |
      from africastalking.SMS import SMS

        sms = SMS(username=${{ AT_USERNAME }}, api_key=${{ AT_API_KEY }}) 

      message = f"{github.event_name} on {github.repository} by {github.actor} has {github.event.workflow_run.conclusion}. Check it out at {github.event.workflow_run.url}"

      response = sms.send(message, [toPhoneNumber])

      print(response)

1. Replace <WORKFLOW_NAME> with the name of the workflow you want to monitor. If you want to monitor all workflows, remove line 7. If you want to monitor multiple workflows, add them separated by a comma. For example: ["<WORKFLOW_NAME>", "<WORKFLOW_NAME>"]

2. Replace toPhoneNumber with the phone number you want to send the SMS to. You can also use a secret. For example: ${{ secrets.toPhoneNumber }}

3. Replace message with the message you want to send. You can also use a secret. For example: ${{ github.event_name }} on ${{ github.repository }} by ${{ github.actor }} has ${{github.event.workflow_run.conclusion}}. Check it out at ${{ github.event.workflow_run.url }}. This will send a message with the event name, repository name, actor, workflow status and workflow URL.

4. Click on Start commit > Commit changes

5. Click on Actions > Your workflow > Run workflow

This approach allows for more flexibility and customization as needed. Including running a custom script to send the SMS.

To see an example of this in action, check out the code in my repo at sms workflow

See the example below of the error notification received:

Conclusion

In this part, we looked at how to send error notifications from our GitHub Actions workflow. We looked at two methods of implementing this. We also looked at how to use the Africas Talking SDK to send the SMS.

Resources

• Africas Talking

• GitHub Actions

• Africas Talking

• Africas Talking SMS API

• Africas Talking SDKs

Thanks for reading! Free free to leave a comment below if you have any questions, suggestions or clarifications. You can also reach out to me on Twitter. or LinkedIn If you found this article helpful feel free to share it with others.

Buy me a coffee here.