La première fois que vous construisez une intégration GitHub, vous passerez une heure à comprendre si vous voulez une GitHub App ou une OAuth App. La doc les traite comme des options équivalentes. Elles ne le sont pas. L'histoire des webhooks suffit la plupart du temps à trancher.
Le résumé court
- GitHub App : installée sur des comptes ou repos, permissions granulaires, webhooks pour les ressources où installée, s'auth comme elle-même avec tokens courts.
- OAuth App : autorisée par l'utilisateur, agit en son nom, webhooks seulement si configurés manuellement, s'auth comme l'utilisateur avec tokens longs.
Pour une intégration sans utilisateur actif (bot CI, automation de revue) : GitHub App. Pour un outil qui agit au nom d'un utilisateur connecté (UI de recherche de code) : OAuth App.
Comment elles reçoivent les webhooks
GitHub Apps
Une URL webhook configurée à la création. À l'installation, GitHub envoie les événements de ce scope. Inclut installation, installation_repositories, et les types d'événements souscrits.
En-tête X-GitHub-Hook-Installation-Target-Type et installation ID pour mint un token par install. Signature HMAC SHA-256 dans X-Hub-Signature-256 — même forme que repo webhooks.
OAuth Apps
Pas de souscription webhook intégrée. Les utilisateurs autorisés doivent créer manuellement des webhooks repo ou org pointant vers l'URL de l'app. Le reach est lié aux souscriptions des utilisateurs.
Certaines équipes créent automatiquement les webhooks via l'API après autorisation. OK, mais vous gérez maintenant un cycle de vie webhook par utilisateur.
L'auth est la vraie différence
GitHub Apps : JWT signé pour mint des installation tokens courts (1h) par install.
const jwt = createAppJwt(APP_ID, PRIVATE_KEY);
const token = await fetchInstallationToken(jwt, INSTALLATION_ID);
const res = await fetch('https://api.github.com/repos/x/y/issues', {
headers: { Authorization: `token ${token}` },
});Tokens scopés à l'install, expirent — fuite a un blast radius limité.
OAuth Apps : tokens utilisateur longs obtenus via OAuth. Fuite = attaquant peut tout ce que l'utilisateur peut. GitHub pousse vers les Apps pour cette raison.
Permissions : scopées vs larges
GitHub Apps : permissions granulaires (read issues, write checks…). L'utilisateur voit la liste exacte.
OAuth Apps : système plus ancien à scopes (repo, read:user). repo donne lecture/écriture sur tous les repos visibles — pas de "lecture seule sur repos spécifiques".
Test en local
Signature identique — voir test webhook GitHub en local. La différence est l'enregistrement de l'URL.
- GitHub App : URL dans les settings de l'app. Installez sur un repo test. Déclenchez.
- OAuth App : pas de webhook propre. Ajoutez un webhook repo manuel ou via API.
Pour OAuth Apps, testez aussi le flow callback — voir test callbacks OAuth en local.
Migrer entre les deux est pénible
D'OAuth App vers GitHub App : pas de migration. Réautorisation utilisateurs, ré-émission tokens, nettoyage webhooks repo. Dix minutes au début pour choisir.
Quand choisir lequel
GitHub App :
- Tourne en autonome ou en réponse à événements.
- Permissions scopées par repo ou org.
- Webhooks liés au scope d'install.
- Listée sur le GitHub Marketplace.
OAuth App :
- UI où l'utilisateur se connecte et agit dans son compte.
- Action exacte au nom de l'utilisateur.
- Pas besoin de webhooks ou setup manuel par repo.
Voir le guide vérification de signature. Rejoignez la waitlist PortPreview.