Get a Mac notification when a GitHub Actions workflow fails

Step 1: turn on GitHub’s own Actions notifications

1. On github.com, open your avatar menu → Settings → Notifications.
2. Under System, find Actions. It defaults to Don’t notify.
3. Choose On GitHub (your notifications inbox), Email, or both, tick Only notify for failed workflows, and save.

With On GitHub selected, the GitHub Mobile app can push those notifications to your phone.

Where GitHub’s notifications fall short

• Only runs you triggered. GitHub notifies you about workflow runs you started. A teammate’s push that breaks main won’t reach you. Scheduled workflows notify whoever created or last edited the schedule.
• No native Mac notification. GitHub documents three channels — the web inbox, email and GitHub Mobile. None of them is a macOS notification banner.
• GitHub Desktop covers pull requests only. It can show a macOS notification when pull request checks fail for the repository you have selected — useful, but not every workflow run. Turn it on under GitHub Desktop → Settings → Notifications, then allow GitHub Desktop in System Settings → Notifications.

Step 2: get a real macOS notification for any run

A menu-bar app that polls the GitHub Actions API closes both gaps: it watches the workflows you pick regardless of who triggered them, and it uses ordinary macOS notifications, so Focus modes and Notification Center work as usual.

ShipBoard does this with a fine-grained personal access token that has only Actions: Read-only and Metadata: Read-only:

1. Create a fine-grained token, choose the repositories, and set Actions and Metadata to Read-only.
2. Install ShipBoard, click +, choose GitHub and paste the token. It’s verified with GitHub, then stored in your Keychain.
3. Tick the workflows to watch. When a run ShipBoard follows goes from running to failed, you get a native notification with the workflow’s name.

Two things to know. ShipBoard follows each workflow’s default branch, and it works with github.com only, not GitHub Enterprise Server. Each check makes roughly two API calls per workflow, so if you watch a lot of workflows, a refresh interval of a minute or two keeps you comfortably inside GitHub’s hourly API limit.

ShipBoard is free and also covers GitLab CI, AWS CodePipeline, Vercel and Netlify. If GitHub Actions is all you use, a single-purpose app may suit you better — see how the options compare. If you also want to see every repository’s runs in one place, read a GitHub Actions dashboard for all your repos.

Which should you use?

Sources

• GitHub Docs: managing GitHub Actions notifications
• GitHub Docs: notifications for workflow runs
• GitHub Docs: configuring notifications in GitHub Desktop
• GitHub Docs: permissions required for fine-grained tokens