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:
- Getting Started with SMS Notifications using Africas Talking and GitHub Actions Part 1
- 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
Lets 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 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:
- An Africas Talking account.
- 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 🔑:
- Sign up on AfricasTalking.com
- 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):
- In your repo, go to Settings > Secrets > Actions
- Add a secret
AT_USERNAME
with your username. - Add a secret
AT_API_KEY
with your API key. - 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:
- Creating a new workflow.
- Adding the error notification to the existing workflow.
Depending on the method you choose and 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:
- In your repository, go to Actions > New workflow > set up a workflow yourself
- Name your workflow. For example,
error-notification.yml
- 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 }}
- 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>"]
- Replace
fromPhoneNumber
with the phone number you want to send the SMS from. You can also use a secret. For example:${{ secrets.fromPhoneNumber }}
- Replace
toPhoneNumber
with the phone number you want to send the SMS to. You can also use a secret. For example:${{ secrets.toPhoneNumber }}
- 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:
- In your repository, go to Actions > Your workflow > Edit
- 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 }}
- Replace
fromPhoneNumber
with the phone number you want to send the SMS from. You can also use a secret. For example:${{ secrets.fromPhoneNumber }}
- Replace
toPhoneNumber
with the phone number you want to send the SMS to. You can also use a secret. For example:${{ secrets.toPhoneNumber }}
- 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. - Click on Start commit > Commit changes
- Click on Actions > Your workflow > Run workflow
- Click on Run workflow
To test 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:
- In your repository, go to Actions > Your workflow > Edit
- 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)
- 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>"]
- Replace
toPhoneNumber
with the phone number you want to send the SMS to. You can also use a secret. For example:${{ secrets.toPhoneNumber }}
- 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. - Click on Start commit > Commit changes
- 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 example below of 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
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.
Top comments (1)
Interesting add 🚀.