# GitHub workflow failed notifications on your phone

> Get a High-priority push notification when a GitHub Actions workflow run fails, times out or can't start.

- Company: GitHub (https://www.justpush.io/recipes/github)
- Event: `workflow_run` (Workflow runs)
- Tags: Developer tools, Monitoring
- Install: https://studio.justpush.io/recipes/github/workflow-failed
- Web page: https://www.justpush.io/recipes/github/workflow-failed

## Setup

1. Click Install in Studio and sign in. The recipe is added to your account and you get a personal webhook URL.
2. In your repository (or organization), go to Settings > Webhooks and click Add webhook.
3. Paste your webhook URL (shown in Studio after install) as the Payload URL and set Content type to application/json.
4. Enter a secret and copy the same secret into JustPush.
5. Choose Let me select individual events, tick Workflow runs, and save. GitHub sends a ping right away.
6. Tick **Workflow runs** in the webhook's events. Only failed, timed-out or unstartable runs push by default. Add `?all=1` to the Payload URL to also get a quiet push when a run passes:
7. ```
8. your webhook URL (shown in Studio after install)?all=1
9. ```
10. On an organization webhook this covers every repository in the organization.
11. GitHub signs every delivery with your secret (`X-Hub-Signature-256`), and JustPush checks it, so requests that don't come from GitHub are rejected.

## Code

Studio calls `handleRequest(request)` with the incoming webhook (`{ method, headers, body, query, raw }`) and sends the message object it returns. Returning `null` sends nothing.

```js
// GitHub → workflow_run (workflow failed)
// Get a High-priority push notification when a GitHub Actions workflow run fails, times out or can't start.
// Docs: https://docs.github.com/en/webhooks/webhook-events-and-payloads#workflow_run

// Conclusions that deserve a push, and how to describe them.
const FAILURES = {
    failure: "failed",
    timed_out: "timed out",
    startup_failure: "couldn't start",
}

// Header names can arrive in any case.
function header(request, name) {
    const headers = request.headers || {}
    const key = Object.keys(headers).find((k) => k.toLowerCase() === name)
    const value = key ? headers[key] : null
    return Array.isArray(value) ? value[0] : value
}

// Only link to real http(s) URLs.
function link(url, cta) {
    return typeof url === "string" && /^https?:\/\//.test(url) ? [{ cta, url }] : []
}

function handleRequest(request) {
    const body = request.body && typeof request.body === "object" ? request.body : {}
    const event = header(request, "x-github-event")

    // Saving the webhook makes GitHub send a ping; confirm the connection quietly.
    if (event === "ping" || (body.zen && body.hook_id)) {
        return {
            title: "🔔 GitHub connected",
            message: `Webhook for ${body.repository?.full_name ?? body.organization?.login ?? "your account"} is working`,
            topic: "GitHub",
            priority: -1,
        }
    }

    // Guard: only workflow_run events. The header decides when it's there; the payload's
    // shape is the fallback (for example in Studio's Test runner).
    if (event ? event !== "workflow_run" : !(body.workflow_run)) {
        console.log(`Ignoring GitHub "${event ?? "unknown"}" event`)
        return null
    }

    const repo = body.repository?.full_name ?? "a repository"
    const run = body.workflow_run
    // ?all=1 on the webhook URL also sends a quiet push for successful runs.
    const all = ["1", "true", "yes"].includes(String(request.query?.all ?? "").toLowerCase())
    const failed = Object.prototype.hasOwnProperty.call(FAILURES, run?.conclusion)

    if (body.action !== "completed" || !run || (!failed && !(all && run.conclusion === "success"))) {
        console.log(`Skipping workflow run "${run?.conclusion ?? body.action}"`)
        return null
    }

    const name = run.name ?? "Workflow"
    const where = [repo, run.head_branch].filter(Boolean).join(" · ")
    const what = run.display_title ?? run.head_commit?.message?.split("\n")[0]
    const who = run.triggering_actor?.login ?? run.actor?.login

    return {
        title: failed ? `❌ ${name} ${FAILURES[run.conclusion]}` : `✅ ${name} passed`,
        message: where + (what ? ` — ${what}` : "") + (who ? ` (@${who})` : ""),
        topic: "GitHub",
        priority: failed ? 1 : -1, // High for broken builds, Low for the optional success pushes
        buttons: link(run.html_url, "View run"),
    }
}
```

## GitHub workflow_run webhook payload (sample)

```json
{
  "action": "completed",
  "sender": {
    "login": "janedoe"
  },
  "workflow": {
    "id": 159038,
    "name": "CI",
    "path": ".github/workflows/ci.yml"
  },
  "repository": {
    "id": 1296269,
    "html_url": "https://github.com/acme/web",
    "full_name": "acme/web"
  },
  "workflow_run": {
    "id": 30433642,
    "name": "CI",
    "actor": {
      "login": "janedoe"
    },
    "event": "push",
    "status": "completed",
    "head_sha": "acb5820ced9479c074f688cc328bf03f341a511d",
    "html_url": "https://github.com/acme/web/actions/runs/30433642",
    "conclusion": "failure",
    "run_number": 562,
    "head_branch": "main",
    "head_commit": {
      "id": "acb5820ced9479c074f688cc328bf03f341a511d",
      "author": {
        "name": "Jane Doe"
      },
      "message": "Fix checkout totals rounding\n\nCloses #88"
    },
    "run_attempt": 1,
    "display_title": "Fix checkout totals rounding",
    "triggering_actor": {
      "login": "janedoe"
    }
  }
}
```

## Signature check

GitHub signs every webhook with an HMAC-SHA256 hash of the request body in the X-Hub-Signature-256 header, made with the secret you set on the webhook. JustPush checks it before the code runs.

## FAQ

### Does this work on iPhone and Android?

Yes. Install the JustPush app from the App Store or Google Play and sign in. Every phone signed in to your account gets the notification.

### Do I need to write code?

No. Install the recipe in Studio, paste your webhook URL into GitHub and you are done. The code is there if you want to change the text, the sound or the buttons.

### Can I change what the notification says?

Yes. After install the recipe's code is yours. Edit it in Studio and test it against the sample payload before you save.

### What does it cost?

JustPush is free for 30 days. After that it's $19.99 a year, or $39.99 once. There is no extra charge for recipes.