Getting Started with SMS Notifications using Africas Talking and GitHub Actions Part 3 - Error Notifications
Tags: tutorial, python, githubactions, github
Published: 2023-10-02 18:26:03

# 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](https://dev.to/ken_mwaura1/getting-started-with-sms-notifications-using-africas-talking-and-github-actions-5de0)
2. [Getting Started with SMS Notifications using Africas Talking and GitHub Actions Part 2](https://dev.to/ken_mwaura1/getting-started-with-sms-notifications-using-africas-talking-and-github-actions-part-2-3j0m)

## 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:

1. An [Africas Talking](https://africastalking.com/) account.
2. A [GitHub](https://github.com) 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:

![Workflow diagram](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/xrf9ciqpz253glukdslb.png)

## 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](https://help.github.com/en/github/getting-started-with-github/create-a-repo). Once you have a repository, follow the steps below to get started.

- Get Africas Talking API keys 🔑:

1. Sign up on [AfricasTalking.com](https://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.

![Settings page](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9t49hj51ar2p5n79ho9m.png)

- 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:

![Secrets dashboard](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4l5cu3gnqklcyq087qtw.png)

## 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 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:

```yml
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 }}
```

4. 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>"]`
5. Replace `fromPhoneNumber` with the phone number you want to send the SMS from. You can also use a secret. For example: `${{ secrets.fromPhoneNumber }}`
6. Replace `toPhoneNumber` with the phone number you want to send the SMS to. You can also use a secret. For example: `${{ secrets.toPhoneNumber }}`
7. 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:

![Workflows](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/185zqp6rkpe4bsq9ee38.png)

### 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:

```yml

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 }}

```

3. Replace `fromPhoneNumber` with the phone number you want to send the SMS from. You can also use a secret. For example: `${{ secrets.fromPhoneNumber }}`
4. Replace `toPhoneNumber` with the phone number you want to send the SMS to. You can also use a secret. For example: `${{ secrets.toPhoneNumber }}`
5. 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.
6. Click on **Start commit > Commit changes**
7. Click on **Actions > Your workflow > Run workflow**
8. 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](https://github.com/alphaolomi/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:

```yml
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)
```

3. 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>"]`
4. Replace `toPhoneNumber` with the phone number you want to send the SMS to. You can also use a secret. For example: `${{ secrets.toPhoneNumber }}`
5. 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.
6. Click on **Start commit > Commit changes**
7. 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](https://github.com/KenMwaura1/Fast-Api-example/blob/main/.github/workflows/sms_notification.yml)

See example below of error notification received:

![SMS notifications](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8c3z8wxgaudk5qxsnlee.png)

## 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](https://africastalking.com/)
- [GitHub Actions](https://docs.github.com/en/actions)
- [Africas Talking](https://africastalking.com/)
- [Africas Talking SMS API](https://developers.africastalking.com/docs/sms)
- [Africas Talking SDKs](https://developers.africastalking.com/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.](https://twitter.com/KenMwaura1) or [LinkedIn](https://www.linkedin.com/in/kennedy-mwaura/) If you found this article helpful feel free to share it with others. 

Buy me a coffee [here](https://www.buymeacoffee.com/kenmwaura1).

![Next time](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/diajdqtjfsq60kke6kcn.gif)