Utwórz GitHub App

Ten poradnik pokazuje, jak nadać serwerowi własną tożsamość w GitHub. Zajmuje to około dwóch minut, robi to wyłącznie właściciel serwera i trzeba to zrobić tylko raz na serwer.

Możesz tego nie potrzebować

Oficjalny build zawiera już GitHubowy identyfikator klienta, więc Zaloguj się przez GitHub działa od razu, bez niczego zarejestrowanego — przepływ urządzenia uwierzytelnia się samym identyfikatorem klienta, więc można go bezpiecznie dostarczać. Zarejestruj własną aplikację, gdy chcesz, aby SERWER działał jako on sam (webhooki, odpytywanie PR-ów i synchronizacja zgłoszeń działające na instalacji aplikacji, a nie na poświadczeniu osoby), albo gdy budujesz ze źródeł.

Aby następnie połączyć własne konto, zobacz Skonfiguruj integrację GitHub.

Dlaczego serwer potrzebuje własnej aplikacji

Z jednej rejestracji wynikają dwa różne zadania, a to aplikacja sprawia, że oba są rzetelne:

Zadanie	Co na nie odpowiada	Dlaczego to ważne
Osoba się loguje	Identyfikator klienta aplikacji, przez przepływ urządzenia	Otrzymujesz poświadczenie, które jest Twoje, na serwerze, na każdym urządzeniu — bez tokenu do wklejania czy rotacji
Serwer działa	Identyfikator aplikacji + klucz prywatny → token instalacji	Webhooki, odpytywanie PR-ów i synchronizacja zgłoszeń przestają zależeć od tego, czy token jednego człowieka wciąż jest ważny

Zwróć uwagę, czego w tej tabeli nie ma: sekretu klienta. Przepływ urządzenia GitHub uwierzytelnia się samym identyfikatorem klienta — zarówno w żądaniu kodu urządzenia, jak i w odpytywaniu o token — więc do logowania nie trzeba przechowywać żadnego sekretu.

Bez własnej aplikacji pierwsza opcja nadal działa dzięki identyfikatorowi klienta dostarczanemu w buildzie; druga spada na poświadczenie właściciela serwera, więc praca w tle opiera się na osobie, która jako pierwsza przeprowadziła konfigurację.

Nie ma przycisku „zainstaluj GitHub App Control Center”

Wspólnie udostępniana GitHub App oznaczałaby jeden współdzielony sekret klienta i jedną wspólną instalację na wszystkich serwerach, więc dostęp każdego obszaru roboczego do repozytoriów przechodziłby przez poświadczenia, których nikt w tym obszarze nie kontroluje. Dlatego każdy serwer ma własną aplikację — ten poradnik pokazuje, jak niewiele to kosztuje.

Wymagania wstępne

• Jesteś właścicielem serwera — operacje providerApps.* są do niego ograniczone, a karta jest niewidoczna dla wszystkich innych
• Konto GitHub albo organizacja, w której możesz tworzyć aplikacje
• Nic publicznie dostępnego: logowanie to przepływ urządzenia, więc serwer nie potrzebuje portu przychodzącego, tunelu, adresu URL wywołania zwrotnego ani domeny

Zarejestruj aplikację

1. Przejdź do github.com/settings/apps/new (w przypadku organizacji: Settings → Developer settings → GitHub Apps → New GitHub App)
2. GitHub App name — dowolna nazwa; Control Center (yourname) wystarczy. Pojawia się przy commitach i komentarzach tworzonych przez serwer
3. Homepage URL — cokolwiek, np. https://github.com/your-name
4. Callback URL — pozostaw pusty. Przepływ urządzenia go nie używa
5. Zaznacz Enable Device Flow. Bez tego jednego ustawienia logowanie nie zadziała
6. Odznacz Webhook → Active, chyba że konfigurujesz webhooki osobno
7. W sekcji Repository permissions przyznaj co najmniej:
   • Contents: Read and write
   • Metadata: Read-only (obowiązkowe)
   • Pull requests: Read and write
   • Issues: Read and write, jeśli używasz GitHub Issues do zgłoszeń, a także do wyszukiwania komentarzy w rozmowach PR przez bota (zobacz Rozmawiaj z Control Center z PR w GitHub)
   • Checks: Read-only, na potrzeby stanu CI na stronie PR
8. W sekcji Where can this GitHub App be installed? wybierz, co pasuje — „Only on this account” jest właściwe dla osobistego serwera
9. Kliknij Create GitHub App

Zbierz trzy wartości

Na stronie aplikacji, zaraz po jej utworzeniu:

Wartość	Gdzie
App ID	Karta General, u góry
Client ID	Karta General, pod „Client secrets”
Private key	Generate a private key — pobierany jest plik .pem

Plik klucza prywatnego pobiera się tylko raz i GitHub już go nie pokaże. Zachowaj go, dopóki go nie wkleisz; zawsze możesz wygenerować kolejny.

Sekret klienta jest opcjonalny i daje dokładnie jedno: jeśli pozostawisz „Expire user authorization tokens” włączone, to on po cichu odnawia czyjś token, zamiast prosić tę osobę o ponowne zalogowanie co osiem godzin. Samo logowanie nigdy go nie używa.

Prostsza konfiguracja to wyłączenie tego wygasania — wtedy sekret nie jest potrzebny nigdzie. Jeśli je zostawisz, wygeneruj sekret i wklej go w Ustawienia → Serwer → Logowanie jednokrotne (karta Aplikacje dostawców) — nie ma dla niego żadnej zmiennej środowiskowej i żadna nie jest wpisana w build, więc zostaje na Twoim serwerze.

Zainstaluj ją na swoim koncie

Aplikacja zarejestrowana, ale niezainstalowana, może uwierzytelniać ludzi, lecz niczego nie odczyta.

1. Na stronie aplikacji otwórz Install App
2. Zainstaluj ją na swoim koncie lub w organizacji
3. Wybierz All repositories albo wskaż te, które ten serwer ma widzieć

Wklej ją do Control Center

1. Przejdź do Ustawienia → Serwer → Logowanie jednokrotne i przewiń do karty Aplikacje dostawców
2. W bloku GitHub ustaw każde pole:
   • Identyfikator aplikacji — numeryczny App ID
   • Klucz prywatny — wklej cały plik .pem, wraz z wierszami BEGIN i END
   • Identyfikator klienta — z tej samej strony
   • Sekret klienta — tylko jeśli go wygenerowałeś (do odświeżania tokenu)
3. Kliknij Test

Klucz jest analizowany w momencie zapisu, więc obcięte lub źle sformatowane wklejenie zostaje odrzucone od razu, a nie dopiero przy żądaniu w tle wiele godzin później. Test idzie dalej i pyta GitHub, na jakich kontach aplikacja jest zainstalowana — „zapisane” i „działa” to dwa różne twierdzenia, a tylko drugie oznacza, że cokolwiek będzie działać.

Punkt kontrolny: blok GitHub pokazuje „Serwer może działać jako on sam, a ludzie mogą się logować”, a wiersz GitHub w Ustawienia → Obszar roboczy → Profil i tożsamość → Hosting kodu oferuje teraz Zaloguj się przez GitHub.

Skonfiguruj to zamiast tego zmiennymi środowiskowymi

W przypadku instalacji headless lub skryptowej serwer wypełnia każde pole ze środowiska, gdy po raz pierwszy nie ma zapisanej wartości:

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

Nie ma dla nich żadnych flag wiersza poleceń — sekret podany w wierszu poleceń może odczytać każdy proces na hoście przez ps. Środowisko to jedyne miejsce, w którym można je skonfigurować, i ma ono pierwszeństwo przed tym, co dostarcza build. .env.template to pełna lista.

Do lokalnego tworzenia oprogramowania plik .env w katalogu głównym repozytorium zawiera te same wartości, a aplikacja desktopowa przekazuje je do uruchamianego serwera. Umieść tam klucz w jednym wierszu: wartość w .env to jeden wiersz, a \n w podwójnych cudzysłowach jest dekodowane jako znak nowego wiersza.

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

GITHUB_APP_ID i GITHUB_APP_PRIVATE_KEY to te same nazwy, które odczytuje już broker tokenów sandboxa, więc host, który skonfigurował drobnoziarniste tokeny agentów, dostaje ścieżkę logowania za darmo. Wypełnianie następuje raz na pole — potem wygrywa zapisana wartość, więc edycja w Ustawieniach nie zostanie cofnięta przy następnym restarcie.

Zrób to samo dla Linear

Linear nie ma przepływu urządzenia, więc jego logowanie to wycieczka przez przeglądarkę i faktycznie wymaga adresu URL wywołania zwrotnego — karta Aplikacje dostawców pokazuje dokładny adres do zarejestrowania.

1. Utwórz aplikację OAuth pod adresem linear.app/settings/api/applications/new
2. Ustaw Callback URL na adres URL pokazany na karcie, dosłownie
3. Wklej Identyfikator klienta i Sekret klienta w bloku Linear
4. Opcjonalnie dodaj klucz API obszaru roboczego — to poświadczenie, którego serwer używa do synchronizacji zgłoszeń, gdy nie poprosił o to żaden człowiek

Rozwiązywanie problemów

Okno logowania informuje, że dostawca nie zwrócił kodu urządzenia

W aplikacji jest wyłączone Enable Device Flow. Włącz je na karcie General i spróbuj ponownie.

Test mówi, że poświadczenia działają, ale aplikacja nie jest nigdzie zainstalowana

Rejestracja i instalacja to osobne kroki. Otwórz Install App na stronie aplikacji i zainstaluj ją.

Test mówi, że nie udało się odczytać klucza prywatnego

Wklej cały plik .pem, łącznie z wierszami -----BEGIN i -----END. Klucz ed25519 lub EC nie może zostać użyty — GitHub Apps podpisują za pomocą RSA.

Członek się zalogował, ale nie widzi żadnych repozytoriów

Aplikacja nie jest zainstalowana na koncie, do którego należą, albo jej instalacja obejmuje inne repozytoria. Własne logowanie daje dostęp tylko do tego, co aplikacja może widzieć.

Powiązane poradniki

• Skonfiguruj integrację GitHub
• Rozmawiaj z Control Center z PR w GitHub
• Połącz host kodu
• Zarządzaj kluczami API
• Skonfiguruj integrację Slack