# GitHub pull request notifications on your phone

> Get a push notification when a pull request is opened, marked ready for review, gets a review request, or is merged.

- Company: GitHub (https://www.justpush.io/recipes/github)
- Event: `pull_request` (Pull requests)
- Tags: Developer tools, Releases
- Install: https://studio.justpush.io/recipes/github/pull-request
- Web page: https://www.justpush.io/recipes/github/pull-request

## 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 Pull requests, and save. GitHub sends a ping right away.
6. Tick **Pull requests** in the webhook's events. Pushes go out when a pull request is opened (not as a draft), marked ready for review, gets a review request, or is merged. Edits, syncs, labels and closes without merging are ignored.
7. 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 → pull_request (pull request)
// Get a push notification when a pull request is opened, marked ready for review, gets a review request, or is merged.
// Docs: https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request

// The pull request actions worth a push.
const ACTIONS = {
    opened: { emoji: "🔀", verb: "opened", priority: 0 },
    ready_for_review: { emoji: "🔀", verb: "ready for review", priority: 0 },
    review_requested: { emoji: "👀", verb: "review requested", priority: 0 },
    merged: { emoji: "🟣", verb: "merged", priority: -1 },
}

// 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 pull_request 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 !== "pull_request" : !(body.pull_request)) {
        console.log(`Ignoring GitHub "${event ?? "unknown"}" event`)
        return null
    }

    const repo = body.repository?.full_name ?? "a repository"
    const pr = body.pull_request
    // GitHub reports a merge as "closed" with merged: true.
    const action = body.action === "closed" && pr?.merged ? "merged" : body.action

    // Drafts aren't ready for eyes yet; closed-without-merge and edits are skipped too.
    if (!pr || !Object.prototype.hasOwnProperty.call(ACTIONS, action) || (action === "opened" && pr.draft)) {
        console.log(`Skipping pull request action "${body.action}"`)
        return null
    }

    const what = ACTIONS[action]
    const who =
        action === "review_requested"
            ? body.requested_reviewer?.login ?? body.requested_team?.name
            : action === "merged"
              ? pr.merged_by?.login
              : pr.user?.login
    const detail =
        action === "review_requested"
            ? who ? `from @${who}` : null
            : who ? `by @${who}` : null
    const branches = pr.head?.ref && pr.base?.ref ? `${pr.head.ref} → ${pr.base.ref}` : null

    return {
        title: `${what.emoji} PR #${pr.number} ${what.verb}: ${pr.title}`,
        message: [repo, branches, detail].filter(Boolean).join(" · "),
        topic: "GitHub",
        priority: what.priority,
        buttons: link(pr.html_url, "View pull request"),
    }
}
```

## GitHub pull_request webhook payload (sample)

```json
{
  "action": "opened",
  "number": 42,
  "sender": {
    "login": "sam-lee"
  },
  "repository": {
    "full_name": "acme/web"
  },
  "pull_request": {
    "base": {
      "ref": "main"
    },
    "head": {
      "ref": "feature/apple-pay"
    },
    "user": {
      "login": "sam-lee"
    },
    "draft": false,
    "state": "open",
    "title": "Add Apple Pay to checkout",
    "merged": false,
    "number": 42,
    "html_url": "https://github.com/acme/web/pull/42"
  }
}
```

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