Vytvořte GitHub App

Tenhle návod ukáže, jak serveru dát vlastní identitu na GitHubu. Zabere to asi dvě minuty, dělá to jen vlastník serveru a na každý server stačí jednou.

Možná ji nepotřebuješ

Oficiální vydání už vozí GitHub client id, takže Přihlásit se přes GitHub funguje hned a nic neregistruješ. Device flow se ověřuje jen tím client id, a proto ho lze bezpečně přibalit do sestavení. Vlastní aplikaci registruj, když chceš, aby server jednal sám za sebe (webhooky, dotazování na PR a synchronizace ticketů na instalaci aplikace, ne na přihlašovacím údaji člověka), nebo když stavíš ze zdrojového kódu.

Vlastní účet připojíš potom podle Nastavte integraci GitHub.

Proč server potřebuje vlastní aplikaci

Z jedné registrace vycházejí dvě různé práce a aplikace je to, co obě drží poctivě:

Práce	Čím se plní	Proč na tom záleží
Přihlásí se člověk	Client id aplikace, přes device flow	Dostaneš přihlašovací údaj, který je tvůj, na serveru a na každém zařízení, bez tokenu k vložení nebo obměně
Jedná server	Id aplikace + soukromý klíč → instalační token	Webhooky, dotazování na PR a synchronizace ticketů přestanou viset na tom, jestli token jednoho člověka ještě platí

V tabulce není client secret. Device flow GitHubu se ověřuje jen client id, jak žádost o device code, tak poll tokenu, takže k přihlášení žádné tajemství nedržíš.

Bez vlastní aplikace ta první pořád funguje přes client id, které vozí sestavení. Ta druhá spadne na přihlašovací údaj vlastníka serveru, takže práce na pozadí visí na tom, kdo server nastavil jako první.

Tlačítko „nainstaluj GitHub App od Control Center“ neexistuje

Distribuovaná GitHub App by znamenala jeden sdílený client secret a jednu sdílenou instalaci na serverech všech, takže přístup k repozitářům každého pracovního prostoru by šel přes údaje, které v tom prostoru nikdo neřídí. Každý server proto vlastní svou aplikaci. Tenhle návod je o tom, jak málo to stojí.

Než začneš

• Jsi vlastník serveru. Operace providerApps.* jsou vázané na něj a kartu nikdo jiný nevidí
• Účet na GitHubu, nebo organizace, ve které umíš zakládat aplikace
• Nic veřejně dosažitelného: přihlášení je device flow, takže server nepotřebuje příchozí port, tunel, callback URL ani doménu

Zaregistruj aplikaci

1. Otevři github.com/settings/apps/new (u organizace: Settings → Developer settings → GitHub Apps → New GitHub App)
2. GitHub App name — cokoli; Control Center (yourname) stačí. Jméno se ukáže u commitů a komentářů, které dělá server
3. Homepage URL — cokoli, třeba https://github.com/your-name
4. Callback URL — nech prázdné. Device flow žádné nemá
5. Zaškrtni Enable Device Flow. Bez tohohle nastavení přihlášení nefunguje
6. Odškrtni Webhook → Active, pokud webhooky nezapojíš zvlášť
7. Pod Repository permissions dej aspoň:
   • Contents: Read and write
   • Metadata: Read-only (povinné)
   • Pull requests: Read and write
   • Issues: Read and write, pokud tickety vedeš v GitHub Issues a kvůli hledání komentářů bota v konverzaci PR (viz Mluvte s Control Center z GitHub PR)
   • Checks: Read-only, kvůli stavu CI na stránce PR
8. Pod Where can this GitHub App be installed? vyber, co sedí. „Only on this account“ je správně pro osobní server
9. Klikni na Create GitHub App

Získej tři hodnoty

Na stránce aplikace, hned po vytvoření:

Hodnota	Kde
App ID	Záložka General, nahoře
Client ID	Záložka General, pod „Client secrets“
Private key	Generate a private key — stáhne se .pem

Soubor se soukromým klíčem se stáhne jednou a GitHub ho už neukáže. Nech si ho, dokud ho nevložíš. Další můžeš vygenerovat kdykoli.

Client secret je volitelný a koupí přesně jednu věc: když necháš „Expire user authorization tokens“ zapnuté, právě on potichu obnoví něčí token, místo aby se člověk musel každých osm hodin přihlásit znovu. Samotné přihlášení ho nepoužívá.

Jednodušší je to vypršení vypnout. Pak tajemství nikde nepotřebuješ. Když ho necháš zapnuté, vygeneruj secret a vlož ho v Nastavení → Server → Jednotné přihlášení (karta Aplikace poskytovatelů). Proměnná prostředí pro něj není a do sestavení se žádná nezapeče, takže zůstane na tvém serveru.

Nainstaluj ji na svůj účet

Aplikace, která je zaregistrovaná a nenainstalovaná, umí lidi ověřit a nepřečte nic.

1. Na stránce aplikace otevři Install App
2. Nainstaluj ji na svůj účet nebo organizaci
3. Zvol All repositories, nebo vyber ty, které má tenhle server vidět

Vlož ji do Control Center

1. Jdi do Nastavení → Server → Jednotné přihlášení a sjeď ke kartě Aplikace poskytovatelů
2. V bloku GitHub vyplň pole:
   • ID aplikace — číselné App ID
   • Soukromý klíč — vlož celé .pem, včetně řádků BEGIN a END
   • Client id — z téže stránky
   • Client secret — jen když jsi nějaké vygeneroval (kvůli obnově tokenu)
3. Klikni na Test

Klíč se při uložení parsuje, takže oříznuté vložení nebo špatný formát se odmítne hned, a ne až na požadavku na pozadí o několik hodin později. Test jde dál a zeptá se GitHubu, na kterých účtech je aplikace nainstalovaná. „Uložené“ a „funguje“ jsou dvě různá tvrzení a jen to druhé znamená, že něco poběží.

Kontrola: blok GitHub hlásí „Server může jednat jako on sám a lidé se můžou přihlásit.“ a řádek GitHub v Nastavení → Pracovní prostor → Profil a identita → Hostování kódu teď nabízí Přihlásit se přes GitHub.

Nastav to radši proměnnými prostředí

U instalace bez rozhraní nebo ze skriptu server každé pole naplní z prostředí poprvé, kdy pro něj nemá uloženou hodnotu:

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

Příznaky příkazové řádky pro ně nejsou. Tajemství na příkazové řádce přečte každý proces na hostiteli přes ps. Prostředí je jediné místo, kam je dáš, a přebije to, co vozí sestavení. Úplný seznam je .env.template.

Při místním vývoji nese tytéž hodnoty .env v kořeni repozitáře a desktop je předá serveru, který spustí. Klíč tam dej na jeden řádek: hodnota v .env je jeden řádek a \n ve dvojitých uvozovkách se dekóduje jako nový řádek.

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

GITHUB_APP_ID a GITHUB_APP_PRIVATE_KEY jsou tatáž jména, která už čte broker tokenů sandboxu. Hostitel nastavený na tokeny agentů s úzkým rozsahem tak dostane přihlášení navíc. Naplnění proběhne u každého pole jen jednou. Potom vyhraje uložená hodnota, takže úprava v Nastavení se dalším restartem nezruší.

Totéž pro Linear

Linear device flow nemá, takže jeho přihlášení je cesta přes prohlížeč a callback URL potřebuje. Karta Aplikace poskytovatelů ukáže přesně tu, kterou zaregistruješ.

1. Vytvoř OAuth aplikaci na linear.app/settings/api/applications/new
2. Callback URL nastav na URL, které karta ukazuje, doslova
3. Do bloku Linear vlož Client ID a Client secret
4. Volitelně přidej API klíč pracovního prostoru. Tím údajem server synchronizuje tickety, když o to nikdo nepožádal

Řešení problémů

Dialog přihlášení hlásí, že poskytovatel nevrátil žádný device code

Enable Device Flow je na aplikaci vypnuté. Zapni ho pod General a zkus to znovu.

Test hlásí, že údaje fungují, ale aplikace není nikde nainstalovaná

Registrace a instalace jsou dva kroky. Na stránce aplikace otevři Install App a nainstaluj ji.

Test hlásí, že soukromý klíč nešel přečíst

Vlož celý soubor .pem, včetně řádků -----BEGIN a -----END. Klíč ed25519 ani EC použít nejde. GitHub Apps se podepisují RSA.

Člen se přihlásil, ale nevidí žádné repozitáře

Aplikace není nainstalovaná na účtu, který je vlastní, nebo její instalace vybírá jiné repozitáře. Jeho vlastní přihlášení pustí jen to, co aplikace smí vidět.

Související návody

• Nastavte integraci GitHub
• Mluvte s Control Center z GitHub PR
• Připojte hostitele kódu
• Spravujte API klíče
• Nastavte integraci Slack