Créer la GitHub App

Ce guide vous montre comment donner à votre serveur sa propre identité GitHub. Il prend environ deux minutes, seul le propriétaire du serveur s’en charge, et il ne doit se faire qu’une fois par serveur.

Vous n’en avez peut-être pas besoin

Une version officielle est déjà livrée avec un identifiant client GitHub, donc Se connecter avec GitHub fonctionne d’emblée sans rien enregistrer — un flux d’appareil s’authentifie avec le seul identifiant client, ce qui est sans risque à livrer. Enregistrez votre propre application lorsque vous voulez que le SERVEUR agisse en son nom (webhooks, interrogation périodique des PR et synchronisation des tickets sur une installation d’application plutôt que sur l’identifiant d’une personne), ou lorsque vous construisez à partir des sources.

Pour connecter ensuite votre propre compte, voir Configurer l’intégration GitHub.

Pourquoi votre serveur a besoin de sa propre application

Une même inscription produit deux tâches différentes, et c’est l’application qui rend les deux honnêtes :

Tâche	Ce qui y répond	Pourquoi c’est important
Une personne se connecte	L’identifiant client de l’application, par le flux d’appareil	Vous obtenez un identifiant qui vous appartient, sur le serveur, sur chaque appareil — sans jeton à coller ni à faire tourner
Le serveur agit	L’identifiant de l’application + la clé privée → jeton d’installation	Les webhooks, l’interrogation périodique des PR et la synchronisation des tickets cessent de dépendre de la validité du jeton d’un humain

Remarquez ce qui ne figure pas dans ce tableau : un secret client. Le flux d’appareil de GitHub s’authentifie avec le seul identifiant client — tant la demande de code d’appareil que l’interrogation du jeton —, de sorte qu’il n’y a aucun secret à conserver pour se connecter.

Sans application qui vous soit propre, la première tâche fonctionne quand même grâce à l’identifiant client livré par la version ; la seconde retombe sur l’identifiant du propriétaire du serveur, de sorte que le travail en arrière-plan repose sur la personne qui s’est configurée en premier.

Il n’existe aucun bouton « Installer la GitHub App de Control Center »

Une GitHub App distribuée impliquerait un secret client partagé et une installation partagée entre les serveurs de tout le monde, de sorte que l’accès aux dépôts de chaque espace de travail passerait par des identifiants que personne dans cet espace de travail ne contrôle. Chaque serveur possède donc sa propre application — ce guide montre à quel point cela coûte peu.

Prérequis

• Vous êtes le propriétaire du serveur — les opérations providerApps.* lui sont réservées, et la carte est invisible pour tout le monde
• Un compte GitHub, ou une organisation dans laquelle vous pouvez créer des applications
• Rien qui soit accessible publiquement : la connexion est un flux d’appareil, donc le serveur n’a besoin d’aucun port entrant, tunnel, URL de rappel ni domaine

Enregistrer l’application

1. Allez à github.com/settings/apps/new (pour une organisation : Settings → Developer settings → GitHub Apps → New GitHub App)
2. GitHub App name — n’importe quoi ; Control Center (yourname) convient. Ce nom apparaît sur les commits et les commentaires que le serveur produit
3. Homepage URL — n’importe quoi, p. ex. https://github.com/your-name
4. Callback URL — laissez-la vide. Le flux d’appareil n’en a pas
5. Cochez Enable Device Flow. C’est le seul paramètre sans lequel la connexion ne peut pas fonctionner
6. Décochez Webhook → Active, sauf si vous câblez les webhooks séparément
7. Sous Repository permissions, accordez au moins :
   • Contents: Read and write
   • Metadata: Read-only (obligatoire)
   • Pull requests: Read and write
   • Issues: Read and write, si vous utilisez GitHub Issues pour les tickets, et pour la recherche de commentaires du bot dans les conversations de PR (voir Parler à Control Center depuis une PR GitHub)
   • Checks: Read-only, pour l’état de l’intégration continue sur la page de la PR
8. Sous Where can this GitHub App be installed?, choisissez ce qui convient — « Only on this account » est le bon choix pour un serveur personnel
9. Cliquez sur Create GitHub App

Recueillir les trois valeurs

Sur la page de l’application, immédiatement après la création :

Valeur	Où
App ID	L’onglet General, près du haut
Client ID	L’onglet General, sous « Client secrets »
Private key	Generate a private key — un fichier .pem se télécharge

Le fichier de clé privée ne se télécharge qu’une fois, et GitHub ne l’affiche plus jamais. Conservez-le jusqu’à ce que vous l’ayez collé ; vous pouvez toujours en générer un autre.

Un secret client est facultatif et n’apporte qu’une seule chose : si vous laissez « Expire user authorization tokens » activé, c’est lui qui renouvelle silencieusement le jeton d’une personne au lieu de lui demander de se reconnecter toutes les huit heures. La connexion elle-même ne l’utilise jamais.

La configuration la plus simple consiste à désactiver cette expiration ; plus aucun secret n’est alors nécessaire. Si vous la laissez activée, générez un secret et collez-le dans Paramètres → Serveur → Authentification unique (la carte Applications fournisseur) — il n’existe aucune variable d’environnement pour lui, et aucune n’est intégrée à une version, de sorte qu’il reste sur votre serveur.

Installer l’application sur votre compte

Une application enregistrée mais non installée peut authentifier des personnes et ne rien lire.

1. Sur la page de l’application, ouvrez Install App
2. Installez-la sur votre compte ou votre organisation
3. Choisissez All repositories, ou sélectionnez celles que ce serveur doit voir

Coller les valeurs dans Control Center

1. Allez dans Paramètres → Serveur → Authentification unique et faites défiler jusqu’à la carte Applications fournisseur
2. Dans le bloc GitHub, renseignez chaque champ :
   • Identifiant d’application — l’App ID numérique
   • Clé privée — collez le fichier .pem au complet, lignes BEGIN et END comprises
   • Identifiant client — depuis la même page
   • Secret client — seulement si vous en avez généré un (pour le renouvellement du jeton)
3. Cliquez sur Tester

La clé est analysée au moment où elle est enregistrée : un collage tronqué ou mal formaté est donc rejeté sur-le-champ plutôt que d’échouer des heures plus tard sur une requête en arrière-plan. Tester va plus loin et demande à GitHub sur quels comptes l’application est installée — « enregistré » et « fonctionne » sont deux affirmations différentes, et seule la seconde signifie que quelque chose s’exécutera.

Point de contrôle : le bloc GitHub affiche « Le serveur peut agir en son nom, et les personnes peuvent se connecter », et la ligne GitHub sous Paramètres → Espace de travail → Profil et identité → Hébergement de code propose désormais Se connecter avec GitHub.

Le configurer plutôt avec des variables d’environnement

Pour une installation sans interface ou automatisée, le serveur initialise chaque champ à partir de l’environnement la première fois qu’il n’a aucune valeur enregistrée :

GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="$(cat control-center.private-key.pem)"
GITHUB_CLIENT_ID=Iv1.0123456789abcdef

Il n’existe aucun indicateur de ligne de commande pour ces valeurs — un secret passé sur la ligne de commande est lisible par tout processus de l’hôte au moyen de ps. L’environnement est le seul endroit où les configurer, et il l’emporte sur ce que la version livre. .env.template en donne la liste complète.

Pour le développement local, le .env à la racine du dépôt porte les mêmes valeurs, et l’application de bureau les transmet au serveur qu’elle lance. Placez la clé sur une seule ligne : une valeur de .env tient sur une ligne, et \n entre guillemets doubles est décodé en saut de ligne.

GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEow…\n-----END RSA PRIVATE KEY-----"

GITHUB_APP_ID et GITHUB_APP_PRIVATE_KEY sont les mêmes noms que lit déjà le courtier de jetons du bac à sable, de sorte qu’un hôte qui a configuré des jetons d’agent à granularité fine obtient la voie de connexion gratuitement. L’initialisation se fait une fois par champ — ensuite, la valeur enregistrée l’emporte, donc une modification faite dans Paramètres n’est pas annulée au prochain redémarrage.

Faites de même pour Linear

Linear n’a pas de flux d’appareil : sa connexion est donc un aller-retour dans le navigateur et elle a bel et bien besoin d’une URL de rappel — la carte Applications fournisseur vous montre exactement celle à enregistrer.

1. Créez une application OAuth à linear.app/settings/api/applications/new
2. Renseignez Callback URL avec l’URL affichée par la carte, textuellement
3. Collez l’Identifiant client et le Secret client dans le bloc Linear
4. Ajoutez facultativement une clé API d’espace de travail — c’est l’identifiant que le serveur utilise pour synchroniser les tickets quand aucun humain n’a fait la demande

Dépannage

La boîte de dialogue de connexion indique que le fournisseur n’a renvoyé aucun code d’appareil

Enable Device Flow est désactivé sur l’application. Activez-le sous General, puis réessayez.

Tester indique que les identifiants fonctionnent, mais que l’application n’est installée nulle part

L’enregistrement et l’installation sont deux étapes distinctes. Ouvrez Install App sur la page de l’application, puis installez-la.

Tester indique que la clé privée n’a pas pu être lue

Collez le fichier .pem au complet, y compris les lignes -----BEGIN et -----END. Une clé ed25519 ou EC ne peut pas être utilisée — les GitHub Apps signent avec RSA.

Un membre s’est connecté, mais ne voit aucun dépôt

L’application n’est pas installée sur le compte qui les possède, ou son installation sélectionne d’autres dépôts. Sa propre connexion n’accorde que ce que l’application est autorisée à voir.

Guides connexes

• Configurer l’intégration GitHub
• Parler à Control Center depuis une PR GitHub
• Connecter un hébergeur de code
• Gérer les clés API
• Configurer l’intégration Slack