While GitHub's email notifications are great for basic success/failure alerting, they can easily get buried in an email inbox, and alerts cannot be triggered from custom events.

In this guide, we will use a simple curl request to send alerts from your GitHub Actions workflows directly to your phone. This creates a searchable, permanent history of your builds, deployments, and test results within the Pulsetray app.

Initial Setup

First, ensure you have downloaded the Pulsetray app and are signed in. You'll need an API key to authenticate your GitHub requests:

  1. Open the Pulsetray app and go to Settings > API keys > Add API key.
  2. Give it a name like "GitHub CI" and click Add key.
  3. Copy the Token immediately. You won't be able to see it again once you leave the screen.

Securing your Token in GitHub

For security, never hardcode your API token in your .yml workflow files. Instead, use GitHub Secrets:

  1. In your GitHub repository, go to Settings > Secrets and variables > Actions.
  2. Click New repository secret.
  3. Name it PULSETRAY_TOKEN and paste your token as the value.

Implementation

The easiest way to start sending notifications is using a standard curl command in a run step. To trigger a notification, all you have to do is open the .yml file of your GitHub action, and paste the following code:

- name: Send notification
  if: always()
  run: |
    curl -X POST https://api.pulsetray.com/v1/notifications \
    -H "Authorization: Bearer ${{ secrets.PULSETRAY_TOKEN }}" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "GitHub Action: ${{ github.workflow }}",
      "body": "Status: ${{ job.status }}\nBranch: ${{ github.ref_name }}",
      "source": "github-actions"
    }'

Great! You should now be receiving a notification everytime your workflow runs. Below you'll find some real use cases for this implementation, so that you know when specific actions fail or succeed.

Use Case Examples

1. Critical Failure Alerts (e.g. Jest/Unit Testing)

You can get an immediate notification whenever a test step fails. To do so, we will use GitHub's status check functions. Place the following code right next to your testing step:

- name: Notify on test failure
  if: failure()
  run: |
    curl -X POST https://api.pulsetray.com/v1/notifications \
    -H "Authorization: Bearer ${{ secrets.PULSETRAY_TOKEN }}" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Tests Failed ❌",
      "body": "Workflow ${{ github.run_id }} failed in the testing phase.",
      "source": "github-actions",
      "androidConfig": { "priority": "high" }
    }'

2. Deployment success

You can also get an immediate notification when a new deployment goes live. You can use the if: success() status check function, placing as the last step of your entire workflow:

- name: Notify on successs
  if: success()
  run: |
    curl -X POST https://api.pulsetray.com/v1/notifications \
    -H "Authorization: Bearer ${{ secrets.PULSETRAY_TOKEN }}" \
    -H "Content-Type: application/json" \
    -d '{
      "title": "Deployment successful ✅",
      "body": "Workflow ${{ github.run_id }} deployed successfully.",
      "source": "github-actions",
      "androidConfig": { "priority": "high" }
    }'

3. Attaching failure screenshots (e.g. Playwright/Cypress)

If a UI test fails, it's helpful to see exactly what went wrong. Pulsetray supports rich media, so you can attach a screenshot directly to the notification:

curl -X POST https://api.pulsetray.com/v1/notifications \
    -H "Authorization: Bearer ${{ secrets.PULSETRAY_TOKEN }}" \
    -F "title=UI Test Failure" \
    -F "body=View the attached screenshot for details." \
    -F "media=@/path/to/playwright/failure-screenshot.png" \
    -F "source=github-actions"

But there's more!

You can use the source and category fields to group your notifications. For example, you could have a "GitHub" source with categories like "Deployments", "Unit Tests", and "Security Scans". This makes your notification tray much easier to navigate. You can find more samples and the entire API reference in the documentation.

Ready to organize your CI/CD alerts? Download Pulsetray and start sending notifications in a few minutes.