GitHub App létrehozása

Ez az útmutató bemutatja, hogyan adhat a szerverének saját GitHub-identitást. Körülbelül két percet vesz igénybe, csak a szerver tulajdonosa végzi el, és szerverenként csak egyszer kell megtenni.

A saját fiókja későbbi összekapcsolásához lásd: GitHub-integráció beállítása.

Miért van szüksége a szerverének saját appra

Egyetlen regisztrációból két különböző feladat származik, és az app az, ami mindkettőt becsületessé teszi:

Feladat	Mi válaszol rá	Miért számít
Egy személy bejelentkezik	Az app kliens-ID-ja, az eszközfolyamaton keresztül	Olyan hitelesítő adatot kap, amely a sajátja, a szerveren, minden eszközén — nincs beilleszteni vagy cserélni való token
A szerver cselekszik	Az app ID-ja + privát kulcs → telepítési token	A webhookok, a PR-lekérdezés és a jegyszinkronizálás többé nem függ attól, hogy egyetlen ember tokenje még érvényes

Figyelje meg, mi nincs ebben a táblázatban: a kliens titok. A GitHub eszközfolyamata kizárólag a kliens-ID-val hitelesít — mind az eszközkód kérésénél, mind a token lekérdezésénél —, így a bejelentkezéshez nincs őrizendő titok.

Saját app nélkül az első továbbra is működik a builddel szállított kliens-ID-val; a második a szerver tulajdonosának hitelesítő adataira esik vissza, így a háttérmunka annak a személynek a hitelesítő adatain nyugszik, aki elsőként állította be a szervert.

Előfeltételek

Ön a szerver tulajdonosa — a providerApps.* műveletek hozzá vannak korlátozva, és a kártya mindenki más számára láthatatlan
GitHub-fiók, vagy egy szervezet, amelyben appokat hozhat létre
Semmi nyilvánosan elérhető dolog: a bejelentkezés egy eszközfolyamat, így a szervernek nem kell bejövő port, alagút, callback URL vagy domain

Az app regisztrálása

Nyissa meg a github.com/settings/apps/new oldalt (szervezet esetén: Settings → Developer settings → GitHub Apps → New GitHub App)
GitHub App name — bármi; a Control Center (yourname) megfelel. Ez jelenik meg azokon a commitokon és hozzászólásokon, amelyeket a szerver tesz
Homepage URL — bármi, például https://github.com/your-name
Callback URL — hagyja üresen. Az eszközfolyamatnak nincs ilyenje
Jelölje be az Enable Device Flow lehetőséget. Ez az az egyetlen beállítás, amely nélkül a bejelentkezés nem működik
Vegye ki a pipát a Webhook → Active jelölőnégyzetből, kivéve, ha a webhookokat külön köti be
A Repository permissions alatt adjon meg legalább ennyit:
- Contents: Read and write
- Metadata: Read-only (kötelező)
- Pull requests: Read and write
- Issues: Read and write, ha GitHub Issues-t használ jegyekhez, és a bot PR-beszélgetésekben folytatott hozzászóláskereséséhez (lásd: Beszélgetés a Control Centerrel GitHub PR-ből)
- Checks: Read-only, a PR-oldali CI-állapothoz
A Where can this GitHub App be installed? alatt válassza, ami illik — személyes szerverhez az „Only on this account” a megfelelő
Kattintson a Create GitHub App gombra

A három érték begyűjtése

Az app oldalán, közvetlenül a létrehozás után:

Érték	Hol
App ID	A General lapon, felül
Client ID	A General lapon, a „Client secrets” alatt
Private key	Generate a private key — egy `.pem` töltődik le

A privát kulcs fájlja egyszer töltődik le, és a GitHub soha többé nem mutatja meg. Őrizze meg addig, amíg be nem illesztette; bármikor létrehozhat újat.

A kliens titok nem kötelező, és pontosan egy dolgot ad: ha az „Expire user authorization tokens” be van kapcsolva, ez az, ami csendben megújítja valaki tokenjét, ahelyett hogy nyolcóránként újra bejelentkezésre kérné. Maga a bejelentkezés soha nem használja.

Az egyszerűbb beállítás, ha ezt a lejáratot kikapcsolja, és akkor sehol nincs szükség titokra. Ha bekapcsolva hagyja, hozzon létre egy titkot, és illessze be a Beállítások → Szerver → Egyszeri bejelentkezés alatt (a Szolgáltatói alkalmazások kártyán) — ehhez nincs környezeti változó, és egyetlen buildbe sincs beépítve, így a szerverén marad.

Telepítés a fiókjára

Egy regisztrált, de nem telepített app hitelesítheti az embereket, és semmit sem olvashat.

Az app oldalán nyissa meg az Install App elemet
Telepítse a fiókjára vagy a szervezetére
Válassza az All repositories lehetőséget, vagy jelölje ki azokat, amelyeket ennek a szervernek látnia kell

Beillesztés a Control Centerbe

Nyissa meg a Beállítások → Szerver → Egyszeri bejelentkezés részt, és görgessen a Szolgáltatói alkalmazások kártyához
A GitHub blokkban állítsa be az egyes mezőket:
- Alkalmazás-ID — a numerikus App ID
- Privát kulcs — illessze be a teljes .pem fájlt, a BEGIN és END sorokkal együtt
- Kliens-ID — ugyanarról az oldalról
- Kliens titok — csak ha létrehozott egyet (a token megújításához)
Kattintson a Teszt gombra

A kulcs a mentés pillanatában kerül feldolgozásra, így a csonka vagy rossz formátumú beillesztés azonnal elutasításra kerül, ahelyett hogy órákkal később egy háttérkérésben hiúsulna meg. A Teszt továbbmegy, és megkérdezi a GitHubot, mely fiókokon van telepítve az app — a „mentve” és a „működik” két különböző állítás, és csak a második jelenti azt, hogy egyáltalán futni fog valami.

Ellenőrzőpont: a GitHub-blokk ezt írja: „A szerver tud magaként viselkedni, és az emberek bejelentkezhetnek.”, és a GitHub sor a Beállítások → Munkaterület → Profil és identitás → Kódtárhely alatt mostantól a Bejelentkezés ezzel: GitHub lehetőséget kínálja.

Helyette konfigurálja környezeti változókkal

Headless vagy szkriptelt telepítésnél a szerver minden mezőt a környezetből tölt fel, amikor először nincs tárolt értéke:

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

Ezekhez nincsenek parancssori kapcsolók — a parancssorban szereplő titkot a gazdagép minden folyamata elolvashatja a ps segítségével. A környezet az egyetlen hely, ahol beállíthatók, és elsőbbséget élvez mindennel szemben, amit a build szállít. A teljes listát a .env.template tartalmazza.

Helyi fejlesztéshez a repó gyökerében lévő .env ugyanezeket az értékeket tartalmazza, és az asztali alkalmazás átadja őket az általa indított szervernek. A kulcsot ott egyetlen sorba írja: a .env-ben egy érték egy sor, és a kettős idézőjelek közötti \n újsorrá alakul.

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

A GITHUB_APP_ID és a GITHUB_APP_PRIVATE_KEY ugyanazok a nevek, amelyeket a homokozó tokenbrókere már olvas, így az a gazdagép, amely beállította a finomszemcsés ügynöktokeneket, ingyen megkapja a bejelentkezési sávot. A feltöltés mezőnként egyszer történik — utána a tárolt érték győz, így a Beállításokban végzett szerkesztést a következő újraindítás nem írja felül.

Ugyanezt tegye a Linear esetében

A Linearnak nincs eszközfolyamata, ezért a bejelentkezése egy böngészőn keresztül zajló oda-vissza út, és szüksége van callback URL-re — a Szolgáltatói alkalmazások kártya megmutatja a pontos URL-t, amelyet regisztrálni kell.

Hozzon létre egy OAuth-alkalmazást a linear.app/settings/api/applications/new címen
Állítsa a Callback URL értékét arra az URL-re, amelyet a kártya mutat, szó szerint
Illessze be a Kliens-ID és a Kliens titok értékét a Linear blokkba
Opcionálisan adjon hozzá egy munkaterületi API-kulcsot — ez az a hitelesítő adat, amelyet a szerver a jegyek szinkronizálásához használ, amikor nem ember kérte

Hibaelhárítás

A bejelentkezési párbeszédablak szerint a szolgáltató nem adott vissza eszközkódot

Az Enable Device Flow ki van kapcsolva az appon. Kapcsolja be a General alatt, és próbálja újra.

A teszt szerint a hitelesítő adatok működnek, de az app sehol sincs telepítve

A regisztráció és a telepítés külön lépések. Nyissa meg az Install App elemet az app oldalán, és telepítse.

A teszt szerint a privát kulcs nem olvasható

Illessze be a teljes .pem fájlt, a -----BEGIN és -----END sorokkal együtt. ed25519 vagy EC kulcs nem használható — a GitHub Appok RSA-val írnak alá.

Egy tag bejelentkezett, de nem lát tárolókat

Az app nincs telepítve arra a fiókra, amely ezeket birtokolja, vagy a telepítése más tárolókat választ ki. A tag saját bejelentkezése csak azt engedélyezi, amit az app láthat.