De GitHub App maken

Deze gids laat zien hoe je je server een eigen GitHub-identiteit geeft. Het kost ongeveer twee minuten, alleen de servereigenaar doet het, en het hoeft maar één keer per server te gebeuren.

Voor het daarna koppelen van je eigen account, zie GitHub-integratie instellen.

Waarom je server een eigen app nodig heeft

Uit één registratie komen twee verschillende taken voort, en de app is wat beide eerlijk maakt:

Taak	Wat het beantwoordt	Waarom het ertoe doet
Een persoon logt in	De client-id van de app, via de device flow	Je krijgt inloggegevens die van jou zijn, op de server, op elk apparaat — zonder token om te plakken of te roteren
De server handelt	Het id van de app + privésleutel → installatietoken	Webhooks, PR-polling en ticketsynchronisatie hangen niet langer af van of het token van één mens nog geldig is

Let op wat niet in die tabel staat: een client secret. De device flow van GitHub authenticeert alleen met de client-id — zowel het verzoek om de apparaatcode als de tokenpoll — dus er is geen geheim te bewaren voor het inloggen.

Zonder een eigen app werkt het eerste nog steeds via de client-id die de build meelevert; het tweede valt terug op de inloggegevens van de servereigenaar, dus achtergrondwerk lift mee op wie zich het eerst heeft aangemeld.

Vereisten

Je bent de servereigenaar — de providerApps.*-bewerkingen zijn daartoe beperkt, en de kaart is onzichtbaar voor alle anderen
Een GitHub-account, of een organisatie waarin je apps kunt aanmaken
Niets dat publiek bereikbaar is: het inloggen is een device flow, dus de server heeft geen inkomende poort, tunnel, callback-URL of domein nodig

De app registreren

Ga naar github.com/settings/apps/new (voor een organisatie: Settings → Developer settings → GitHub Apps → New GitHub App)
GitHub App name — maakt niet uit; Control Center (yourname) is prima. Het verschijnt bij commits en reacties die de server plaatst
Homepage URL — maakt niet uit, bijvoorbeeld https://github.com/your-name
Callback URL — laat dit leeg. De device flow heeft er geen
Vink Enable Device Flow aan. Dit is de enige instelling zonder welke het inloggen niet kan werken
Vink Webhook → Active uit, tenzij je webhooks apart aansluit
Ken onder Repository permissions minstens het volgende toe:
- Contents: Read and write
- Metadata: Read-only (verplicht)
- Pull requests: Read and write
- Issues: Read and write, als je GitHub Issues voor tickets gebruikt, en voor het zoeken in PR-gesprekken door de bot (zie Met Control Center praten vanuit een GitHub-PR)
- Checks: Read-only, voor de CI-status op de PR-pagina
Kies onder Where can this GitHub App be installed? wat past — “Only on this account” is goed voor een persoonlijke server
Klik op Create GitHub App

De drie waarden verzamelen

Op de pagina van de app, direct na het aanmaken:

Waarde	Waar
App ID	Het tabblad General, bovenaan
Client ID	Het tabblad General, onder “Client secrets”
Private key	Generate a private key — er wordt een `.pem` gedownload

Het privésleutelbestand wordt één keer gedownload en GitHub toont het daarna nooit meer. Bewaar het tot je het hebt geplakt; je kunt altijd een nieuwe genereren.

Een client secret is optioneel en levert precies één ding op: als je “Expire user authorization tokens” AAN laat staan, is dat wat iemands token stil vernieuwt in plaats van hen elke acht uur opnieuw te laten inloggen. Het inloggen zelf gebruikt het nooit.

De eenvoudiger opzet is die vervaldatum UIT te zetten; dan is er nergens een geheim nodig. Laat je hem aan, genereer dan een secret en plak die in Instellingen → Server → Single sign-on (de kaart Provider-apps) — er bestaat geen omgevingsvariabele voor, en er is er ook geen in een build ingebakken, dus hij blijft op je server.

Installeer hem op je account

Een app die is geregistreerd maar niet geïnstalleerd, kan mensen authenticeren en niets lezen.

Open op de pagina van de app Install App
Installeer hem op je account of organisatie
Kies All repositories, of selecteer de repos die deze server mag zien

Plak hem in Control Center

Ga naar Instellingen → Server → Single sign-on en scroll naar de kaart Provider-apps
Stel in het blok GitHub elk veld in:
- App-id — het numerieke App ID
- Privésleutel — plak het hele .pem-bestand, inclusief de regels BEGIN en END
- Client-id — van dezelfde pagina
- Client-secret — alleen als je er een hebt gegenereerd (voor tokenvernieuwing)
Klik op Testen

De sleutel wordt geparseerd op het moment dat hij wordt opgeslagen, dus een afgekapte of verkeerd opgemaakte plak wordt daar en dan geweigerd in plaats van uren later te falen bij een achtergrondverzoek. Testen gaat verder en vraagt GitHub op welke accounts de app is geïnstalleerd — “opgeslagen” en “werkt” zijn verschillende beweringen, en alleen de tweede betekent dat er iets gaat draaien.

Checkpoint: bij het GitHub-blok staat “De server kan namens zichzelf handelen en mensen kunnen inloggen”, en de rij GitHub onder Instellingen → Werkruimte → Profiel en identiteit → Codehosting biedt nu Inloggen met GitHub aan.

Configureer hem in plaats daarvan met omgevingsvariabelen

Voor een headless of gescripte installatie vult de server elk veld vanuit de omgeving de eerste keer dat er nog geen opgeslagen waarde is:

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

Er zijn geen command-lineflags voor deze waarden — een secret op een commandoregel is via ps leesbaar door elk proces op de host. De omgeving is de enige plek om ze te configureren, en die gaat vóór wat de build ook meelevert. .env.template is de volledige lijst.

Voor lokale ontwikkeling bevat de .env in de hoofdmap van de repo dezelfde waarden, en de desktop geeft ze door aan de server die hij start. Zet de sleutel daar op één regel: een waarde in .env is één regel, en \n tussen dubbele aanhalingstekens wordt gedecodeerd naar een nieuwe regel.

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

GITHUB_APP_ID en GITHUB_APP_PRIVATE_KEY zijn dezelfde namen die de tokenbroker van de sandbox al leest, dus een host die fijnmazige agenttokens heeft geconfigureerd krijgt de inlogroute er gratis bij. Het vullen gebeurt één keer per veld — daarna wint de opgeslagen waarde, dus een bewerking in Instellingen wordt niet ongedaan gemaakt door de volgende herstart.

Doe hetzelfde voor Linear

Linear heeft geen device flow, dus het inloggen verloopt via een rondje door de browser en heeft wél een callback-URL nodig — de kaart Provider-apps toont je precies welke je moet registreren.

Maak een OAuth-applicatie aan op linear.app/settings/api/applications/new
Stel de Callback URL in op de URL die de kaart toont, letterlijk
Plak de Client ID en Client secret in het blok Linear
Voeg optioneel een API-sleutel voor de werkruimte toe — dat zijn de inloggegevens waarmee de server tickets synchroniseert wanneer geen mens erom heeft gevraagd

Probleemoplossing

Het inlogvenster zegt dat de provider geen apparaatcode heeft teruggegeven

Enable Device Flow staat uit bij de app. Zet het aan onder General en probeer het opnieuw.

Testen zegt dat de inloggegevens werken, maar de app is nergens geïnstalleerd

Registratie en installatie zijn aparte stappen. Open Install App op de pagina van de app en installeer hem.

Testen zegt dat de privésleutel niet kon worden gelezen

Plak het hele .pem-bestand, inclusief de regels -----BEGIN en -----END. Een ed25519- of EC-sleutel kan niet worden gebruikt — GitHub Apps ondertekenen met RSA.

Een lid is ingelogd maar ziet geen repositories

De app is niet geïnstalleerd op het account dat eigenaar is van die repositories, of de installatie ervan selecteert andere repositories. Hun eigen login geeft alleen toegang tot wat de app mag zien.