github-integration

Files (2)

• SKILL.md
• SKILL.md.lock

SKILL.md (first lines)

<!-- bodyRef: skills/sources/github-integration.md -->

<!-- Generated by `harness skills bootstrap`. Edit to tune; re-run to regenerate. -->
<!-- Static skills point at live docs by design — do not hardwire version-pinned API here. -->

# GitHub Integration (correct + secure)

This project reads release diffs, PRs, issues, and docs from GitHub and runs its long jobs on a **GitHub Actions runner** (LangGraph worker), with a **Next.js/Vercel** dashboard + API routes as the control surface. That gives three distinct GitHub trust boundaries — get the auth model right for each:

1. **Runner → GitHub API** (read diffs/PRs/issues): prefer the Actions `GITHUB_TOKEN`, or a GitHub App installation token for cross-repo / dashboard-triggered runs.
2. **GitHub → Next.js webhook** (release tag, workflow_dispatch echo): inbound, untrusted — **must** verify the signature.
3. **Dashboard → GitHub** (manual run / workflow_dispatch): server-side only, never from the React client.

## Pull current docs first

Fetch these before writing integration code — APIs and limits change:
- Validating webhook deliveries: https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
- About GitHub App authentication: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app
- Generating an installation access token: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app
- REST API best practices (rate limits, retries, conditional requests): https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api
- Security hardening for GitHub Actions: https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions
- Managing personal access tokens (fine-grained vs classic): https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
- Octokit.js (TS): https://github.com/octokit/octokit.js — auth `@octokit/auth-app`, `@octokit/plugin-throttling`, `@octokit/plugin-retry`, `@octokit/webhooks`
- PyGithub auth: https://pygithub.readthedocs.io/en/stable/examples/Authentication.html

## Auth & secrets (timeless rules, current specifics)

- **Pick the weakest sufficient credential.** Inside an Actions job, the built-in `GITHUB_TOKEN` is auto-scoped and expires when the job ends — use it for same-repo reads. For cross-repo or dashboard-triggered runs, use a **GitHub App installation token**, not a human PAT.
- **GitHub App flow:** sign a short-lived JWT with the App private key (app-level auth) → `POST /app/installations/{id}/access_tokens` to mint an **installation token that expires in 1 hour**. Scope it down with the `repositories`/`repository_ids` and `permissions` body params; a token can never exceed the App's granted permissions. Let the SDK refresh it — `@octokit/auth-app` (TS) and PyGithub `Auth.AppAuth(...).get_installation_auth(...)` cache + auto-refresh.
- **If you must use a PAT, use a fine-grained one** scoped to specific repos + minimal permissions with an expiry — never a classic PAT (all-repo access).
- **Never** put credentials in client components, `NEXT_PUBLIC_*` env vars, logs, or LangGraph state that gets persisted to Aurora/S3. The App private key and webhook secret live only in Actions/Vercel/AWS env secrets (per AGENTS.md guardrails). Treat the installation token as ephemeral — do not persist it.
- In Actions, set `permissions:` to least-privilege (default read-only contents) and grant per-job; mask any derived secrets with `::add-mask::`.

## Webhook verification (inbound, untrusted)

- GitHub signs the **raw request body** with HMAC-SHA256 keyed by your webhook secret and sends it in the **`X-Hub-Signature-256`** header (`sha256=<hex>`). Ignore the legacy SHA1 `X-Hub-Signature`.
- Verify over the **raw bytes** — in Next.js App Router read `await req.text()` (or disable body parsing in Pages API routes); JSON-parsing first changes the bytes and breaks the HMAC.
- **Constant-time compare** only: `crypto.timingSafeEqual` (Node) / `hmac.compare_digest` (Python). Never `==`. A missing header means no secret is configured — reject.
- Prefer the library: `@octokit/webhooks` `verifyAndReceive(...)` (TS). Reject before doing any work.

## Idempotency & retries

- GitHub **webhooks are at-least-once** — the same delivery can arrive twice. Dedupe on the **`X-GitHub-Delivery`** UUID (and respect `X-GitHub-Event`); record processed delivery IDs in Aurora and no-op on repeats. Make LangGraph entry from a webhook idempotent per `release_run_id`.
- **Respond 2xx fast** (within ~10s) and hand the job to the Actions runner; long synchronous work in the webhook handler causes GitHub to time out and redeliver.
- **Outbound retries:** on 429/403 with `retry-after`, honor it; else if `x-ratelimit-remaining: 0`, wait until `x-ratelimit-reset`; otherwise back off ≥60s with exponential backoff. For **secondary** limits, serialize writes and wait ≥1s between mutating calls. Octokit's throttling + retry plugins implement this — enable them rather than hand-rolling.
- **Cut quota with conditional requests:** send `If-None-Match` with a stored `ETag`; a `304` doesn't count against the primary limit. Paginate via Link headers / `octokit.paginate`, not hand-built URLs.
- Read-heavy collectors (diff/PR/issue fetch) are naturally retry-safe; make any write (comments, status checks) idempotent by searching for an existing artifact first — GitHub has no idempotency-key header.

## Test/sandbox vs production

- Local/dev: drive webhooks with the `gh` CLI or a tunnel + a **separate dev App / dev webhook secret**; never the prod secret. The spec defers Secrets Manager — for the MVP keep dev and prod secrets in distinct Actions/Vercel env scopes.
- Add a replay/fixture path: store sample delivery payloads and run verification + the LangGraph entry node against them in tests (Playwright/integration) so you don't hit live GitHub.
- Pin any **third-party Actions to a full commit SHA** (tags are mutable); pass untrusted GitHub context (PR titles, issue bodies — which this engine ingests as evidence) through env vars, never interpolated into shell. Avoid `pull_request_target` with checkout of untrusted code.

## Checklist

- [ ] Credential is the weakest sufficient: `GITHUB_TOKEN` > App installation token > fine-grained PAT; no classic PAT.
- [ ] App private key + webhook secret only in env secrets; never in client, logs, or persisted graph state.
- [ ] Installation tokens minted on demand, repo/permission-scoped, treated as 1-hour ephemeral.
- [ ] Webhook verified: `X-Hub-Signature-256`, HMAC-SHA256 over **raw body**, constant-time compare.
- [ ] Webhook handler returns 2xx fast; heavy work deferred to the runner.
- [ ] Deliveries deduped on `X-GitHub-Delivery`; graph entry idempotent per release run.
- [ ] Outbound calls honor `retry-after` / `x-ratelimit-*` with backoff; throttling+retry plugins enabled.
- [ ] ETag conditional requests + Link-header pagination in collectors.
- [ ] Actions: least-privilege `permissions:`, third-party actions SHA-pinned, untrusted input via env not inline script.
- [ ] Dev uses a separate App/secret; tests run against stored fixtures, not live GitHub.

## Gotchas

- **JSON-parsing the webhook body before HMAC** is the #1 silent failure: Next.js/Express JSON middleware re-serializes the body, changing bytes so the signature never matches. Capture the raw body first.
- **Installation token cached past 1h.** If you stash the token in long-lived LangGraph state (a job can outlive the hour during Playwright/ffmpeg media steps), later API calls 401. Re-mint or let the SDK auth strategy refresh; don't cache the string.
- **`GITHUB_TOKEN` can't trigger downstream workflows** — events made with it (e.g. pushing a tag, opening a PR) won't fire another Actions run, by design. If a dashboard-triggered run must kick off another workflow, use the App token or `workflow_dispatch`.
- **Default `GITHUB_TOKEN` may be read-only** (org/repo policy), so creating commit statuses or comments silently 403s — declare the needed `permissions:` per job.
- **Skipping dedupe on `X-GitHub-Delivery`** means a redelivered release tag spawns a duplicate `release_run_id` and double content generation/Bedrock spend.
- **Secondary rate limits are not the primary limit** and don't show in `x-ratelimit-remaining`; bursting concurrent PR/issue fetches trips them and can suspend the integration. Serialize and pace mutating calls.
- **`pull_request_target` + checkout of the PR head runs untrusted code with secrets** — and this engine deliberately ingests PR/issue text as evidence, so treat every such field as injection-capable; never interpolate it into a shell step.
- **Fine-grained PAT can't reach some APIs** (e.g. Checks) and can't span multiple orgs — if a collector needs those, you need a GitHub App, not a PAT.
- **GraphQL has a separate, point-based rate budget** from REST; mixing both (e.g. GraphQL for PR data, REST for diffs) means tracking two quotas.
- _none observed yet for ElevenLabs/ffmpeg interactions with GitHub auth_

<!-- sources fetched at generation: https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries, https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app, https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app, https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api, https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions, https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens, https://github.com/octokit/octokit.js, https://pygithub.readthedocs.io/en/stable/examples/Authentication.html -->

From ichiorca/shipsignal, Apache-2.0.

More from ichiorca/shipsignal