# Make a finished workflow buzz your phone.

> Get GitHub Actions results as push notifications. Add a Pocket Alert step to your workflow and catch failed builds or finished deploys on your phone in under a second.

<!-- source: https://pocketalert.app/use-cases/github-actions-alerts -->

Pocket Alert sends GitHub Actions results to your phone as push notifications. Add one curl step to a workflow, and when a build, deploy, or release finishes, the result hits your iPhone or Android in under a second — no watching the Actions tab.

## Three steps to GitHub Actions alerts on your phone

1. **Create an application** — Add an application in Pocket Alert and save your API key as the POCKETALERT_API_KEY repo secret.
2. **Wire up the step** — Add a notify step that curls the messages API, using if: failure() and if: success() to pick outcomes.
3. **Map and ship** — Pull repo, sha, and workflow into the message. The next run buzzes your phone.

## From workflow run to lock screen

Your workflow already knows when a job finishes. Pocket Alert turns that moment into a push you cannot miss.

- **One step in your workflow** — A single curl call against the messages API turns any workflow step into a push. No runner setup, no extra service.
- **Key as a repo secret** — Read your API key from ${{ secrets.POCKETALERT_API_KEY }} so it stays out of logs and rotates from the dashboard.
- **Alert on the outcomes you choose** — Pair if: failure() and if: success() to push failed builds and green deploys as separate, clearly labeled messages.
- **A channel per repo** — Each application has its own ID, so per-repo and per-environment runs stay in separate channels.
- **Sub-second delivery** — The step fires the moment the job ends, so the result hits your phone in under a second.
- **Full run context** — Pull github.repository, github.sha, and github.workflow into the message so you know exactly which run it was.

## Send GitHub Actions alerts to your phone

### 1. Create an application and save your API key

Add an application in Pocket Alert and copy your API key. Save it as a repository secret named `POCKETALERT_API_KEY` under Settings → Secrets and variables → Actions.

### 2. Add a notify step that calls the messages API

```
- name: Notify on failure
  if: failure()
  run: |
    curl -X POST "https://api.pocketalert.app/v1/messages" \
      -H "Token: ${{ secrets.POCKETALERT_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{"title":"Build failed","message":"${{ github.workflow }} on ${{ github.ref_name }} (${{ github.sha }})","level":"high"}'

- name: Notify on success
  if: success()
  run: |
    curl -X POST "https://api.pocketalert.app/v1/messages" \
      -H "Token: ${{ secrets.POCKETALERT_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{"title":"Deploy succeeded","message":"${{ github.repository }}@${{ github.sha }}"}'
```

### 3. Route to a specific application

Add `application_id` to the body to send the push to one app (find the TID on the dashboard):

```
-d '{"title":"Release shipped","message":"${{ github.repository }} ${{ github.ref_name }}","application_id":"qm47b9pzxzxg"}'
```

The [getting started docs](https://info.pocketalert.app/getting-started.html) show every field the messages API accepts.

## FAQ

### How do I get GitHub Actions alerts on my phone?

Add a step that runs curl against https://api.pocketalert.app/v1/messages with your API key in the Token header. Put it at the end of the job so a finished deploy or a failed build pushes straight to your phone.

### How do I keep the key secret?

Store your API key as a repository secret and read it with ${{ secrets.POCKETALERT_API_KEY }}, sent in the Token header. The key never appears in logs and you rotate it from the Pocket Alert dashboard.

### Can I alert only on failure?

Use if: failure() and if: success() on two separate steps. A failed build fires one message, a green deploy fires another, so you can wire only the outcomes you care about.

### Can I split alerts per repo?

Give each repo or environment its own application. Frontend, backend, and release workflows land in separate channels you can mute independently.

### Can I include the commit and workflow?

Reference run context like ${{ github.repository }}, ${{ github.sha }}, and ${{ github.workflow }} in the message body so the push tells you exactly which run finished.

### Which endpoint does the step call?

The step calls https://api.pocketalert.app/v1/messages with a Token header and a JSON body of title and message. Add application_id to route the push to a specific app.

### Can a failed build be louder than a successful one?

Add "level":"high" to the failure step body and the push cuts through Focus on iPhone and rings prominently on Android; "level":"critical" goes further and bypasses Do Not Disturb entirely. Green-deploy pings can go out as "level":"silent" so they land in your history without a buzz.