Chapter 27Lesson 03~170 minutes

GitHub Apps, OAuth Apps, Webhooks, Checks API, and Event-Driven Integrations: Configuration, Design Choices, and Tradeoffs

Choose deliberately among App/OAuth/PAT identity, webhook/polling triggers, installation scope, token lifecycle, and check/status/comment feedback surfaces.

Identity designPollingInstallation scopeFeedbackTradeoffs

Learning objectives

Choose GitHub App versus OAuth/PAT from ownership and authorization requirements.
Choose webhook, polling, or hybrid reconciliation from latency/reliability needs.
Separate App permission from installation repository scope.
Choose Checks, statuses, issues, or comments as feedback surfaces.
Design token expiry, event subscription, and GHES boundaries explicitly.

1. Design starts with authority and causality

Lesson 2 proved the mechanics locally. Production design asks two separate questions: who should be allowed to act and how should the service learn that something changed? GitHub App versus OAuth/PAT answers the identity question; webhook versus polling answers the causality question. Do not choose them as fashionable technologies—choose them from ownership, scope, latency, lifecycle, and failure requirements.

2. GitHub App versus OAuth App versus PAT

Choice	Prefer when	Main security/governance property	Main tradeoff
GitHub App	Service/bot automation, multi-repository integration, long-lived platform component	Dedicated bot identity; fine-grained permissions; repository installation selection; short-lived installation tokens; central App webhooks	Requires App registration, private-key lifecycle, installation/token machinery
OAuth App	Primarily user-authorized interaction, especially legacy integrations or enterprise-level resources not covered by App permissions	Acts as user under OAuth scopes and user access	Broader scope model; app continuity remains tied to user authorization
Fine-grained PAT	Small personal/admin script whose owner is intentionally the actor	Selected repositories/resources and explicit permissions	Still a user credential; lifecycle/ownership and rotation are human responsibilities
Machine user	Legacy compatibility that truly needs a user-shaped identity	Normal user authorization model	Password/2FA/token/user lifecycle, possible seat cost, and broad account blast radius

If the service must continue when an employee leaves, that is strong evidence for a GitHub App installation identity rather than a human-owned PAT or machine-user workaround.

3. Webhook versus polling

Dimension	Webhook	Polling
Latency	Near-real-time delivery, though not guaranteed immediate	Bounded by polling interval
API budget	Receives events without repeatedly listing resources	Consumes API calls even when nothing changed
Failure mode	Endpoint availability, signature validation, missed delivery recovery, out-of-order events	Checkpoint/cursor correctness, missed pages, rate limits, duplicate observations
Security	Inbound HTTPS + webhook secret/HMAC + event validation	Outbound API token only
Best use	Continuous event-driven integration	Reconciliation, sparse one-off checks, recovery audit

Reliable systems often combine both: webhook for prompt notification and periodic/recovery reconciliation to repair drift. Do not convert that into duplicate writes—both paths must converge on the same desired-state/idempotency logic.

4. Repository versus organization installation scope

A GitHub App installation on an account may be limited to selected repositories or all repositories. “All repositories” is not a convenience default; it is a larger authorization domain. A service that manages three repositories should generally be installed on those three, with an explicit process to approve another repository later.

Organization-owned integrations can centralize App ownership and policy, but ownership does not automatically grant every repository. Chapter 28 will go deeper on teams/roles/enterprise policy. Here the rule is simpler: separate App permissions (what resource operations the software can perform) from installation repository selection (where those permissions apply).

5. Checks API versus commit statuses, Issues, and comments

Feedback surface	Use when	Strength	Cost/noise
Check run	Automated analysis tied to a commit needs rich status/output/annotations/re-run UX	First-class commit/PR automation feedback	Requires GitHub App Checks write identity for mutation
Commit status	Simple pass/fail/pending context is enough	Small contract and widely understood by branch rules	Less rich diagnostic structure
Issue	The result is work that needs ownership/discussion over time	Durable triage object	Can create issue spam if every run opens one
PR/Issue comment	Human-readable contextual note is useful	Visible in conversation	High noise; poor machine-state primitive; duplicates are common without markers

A branch rule can consume status/check names, but that does not mean every event-driven service should be a merge gate. Separate advisory feedback from policy-blocking feedback so an integration outage does not accidentally halt unrelated development.

6. Installation-token design and expiry

Installation access tokens expire after one hour. Cache a valid token until near expiry rather than minting a token for every webhook, but never assume a cached token remains authorized after uninstall/permission changes. A 401 may mean expiry/revocation; a 403 often means authorization/policy. Refreshing credentials without diagnosing a 403 can hide the real problem and increase request volume.

The App JWT used to mint installation tokens has a much shorter window: its exp must be no more than ten minutes ahead. Keep App private-key operations on trusted server infrastructure, not in browser/mobile code.

7. Event and permission matrices are deployable policy

Keep the App's event subscriptions in the same review conversation as its permissions. Subscribing to issues, pull_request, push, check_suite, and organization events “just in case” increases payload volume, private metadata exposure, storage obligations, and unexpected code paths. Require a one-line business reason for every event and permission.

Requirement	Identity	Events	Permissions	Installation
Read PR metadata and report external analysis as check	GitHub App	pull_request; optionally check_run for rerun	Pull requests read; Checks write; Contents read only if analyzer needs source	Selected repositories
Website login only	GitHub App user auth or OAuth App	No repository webhook required	Only user/resource access needed by product	As required by chosen app model
Nightly personal repo inventory	Fine-grained PAT or gh authenticated user	None	Metadata/contents read as required	Selected user repositories
Organization-wide policy service	GitHub App	Only events policy actually consumes	Fine-grained repo/org permissions	Organization install; selected repos unless policy explicitly covers all

8. GitHub.com, Enterprise Cloud, and GHES are deployment boundaries

GitHub Apps, OAuth Apps, webhook endpoint URLs, REST base URLs, event availability, and permission sets can differ across GitHub.com and GitHub Enterprise Server releases. An App created on GitHub.com is not automatically an App registration on a separate GHES host. Build configuration around an explicit host/base URL and verify the documentation line for the target GHES version.

Mandatory path: All Chapter 27 exercises remain GitHub.com/public/free-compatible or local fixtures. Enterprise administration and internet-reachable webhook hosting are not required.

9. Worked decision: an internal PR policy analyzer

Requirements: react to PR changes in 20 repositories, read changed-file metadata, publish line-level findings, continue working when individual engineers leave, and avoid storing a cloud key. The best fit is a GitHub App installed on the selected 20 repositories, subscribed to the minimum PR/check events, with Pull requests read + Checks write and source permission only if analysis actually needs it. Webhooks trigger work; a reconciliation task checks missed deliveries. A PAT would tie service continuity to a user. An OAuth App adds no value because actions do not need to be attributed to the interactive user. Comments are rejected as the primary result because they create noisy duplicate conversation rather than structured check state.

Knowledge check

A service must outlive the employee who installed it and only touch selected repositories. Which identity is the default fit?

Why might a production service use both webhooks and occasional reconciliation polling?

Does installing an App on an organization automatically mean it can access every repository?

A CI tool only needs pass/fail. Why might commit status be preferable to a check run?

Should a 403 from an installation token be fixed by minting a new token immediately?

Summary

Choose identity, trigger, installation scope, and feedback surface independently. GitHub Apps are the usual service-identity default; OAuth Apps remain user-centric; PATs fit bounded human-owned automation. Webhooks scale event notification, polling/reconciliation repairs drift. Installation repository selection and permissions jointly define blast radius, while check/status/comment surfaces serve different feedback needs.

Next lesson

GitHub Apps, OAuth Apps, Webhooks, Checks API, and Event-Driven Integrations: Diagnostics, Failure Modes, Security, and Performance

Official references

Keep the academy open

Support free, practical DevOps education.

Every lesson is designed to remain readable in a browser, downloadable from GitHub, and usable without a paid learning platform. Contributions help expand and maintain the curriculum.

Ethereum / ERC-20

0x716c4Ab160C4B66F31a28AE2448BfF68fc3a2ef0 Send only Ethereum/ERC-20 compatible assets to this address.