Створити GitHub App

Цей посібник показує, як дати вашому серверу власну ідентичність у GitHub. Це займає близько двох хвилин, робить це лише власник сервера, і потрібно це один раз на сервер.

Офіційна збірка вже постачається з GitHub-ID клієнта, тож Увійти через GitHub працює одразу й без реєстрації — потік із кодом пристрою автентифікується самим лише ID клієнта, тож його безпечно постачати. Реєструйте власний застосунок, коли хочете, щоб СЕРВЕР діяв від свого імені (вебхуки, опитування PR і синхронізація тікетів працюють на установці застосунку, а не на облікових даних людини), або коли збираєте з вихідного коду.

Щоб після цього підключити власний обліковий запис, див. Налаштувати інтеграцію GitHub.

Чому вашому серверу потрібен власний застосунок

З однієї реєстрації виходять дві різні задачі, і саме застосунок робить обидві чесними:

Задача	Що на неї відповідає	Чому це важливо
Людина входить	ID клієнта застосунку, через потік із кодом пристрою	Ви отримуєте облікові дані, які належать вам, на сервері й на кожному пристрої — без токена, який потрібно вставити чи ротувати
Сервер діє	ID застосунку + приватний ключ → токен установки	Вебхуки, опитування PR і синхронізація тікетів перестають залежати від того, чи токен однієї людини ще дійсний

Зверніть увагу, чого в цій таблиці немає: секрету клієнта. Потік із кодом пристрою в GitHub автентифікується самим лише ID клієнта — і запит коду пристрою, і опитування токена, — тож для входу не потрібно зберігати жодного секрету.

Без власного застосунку перше все одно працює через ID клієнта, який постачає збірка; друге ж спирається на облікові дані власника сервера, тож фонова робота тримається на тому, хто налаштував сервер першим.

Передумови

Ви — власник сервера: операції providerApps.* доступні лише йому, і картка невидима для всіх інших
Обліковий запис GitHub або організація, у якій ви можете створювати застосунки
Нічого публічно доступного: вхід — це потік із кодом пристрою, тож серверу не потрібні вхідний порт, тунель, URL зворотного виклику чи домен

Зареєструйте застосунок

Перейдіть на github.com/settings/apps/new (для організації: Settings → Developer settings → GitHub Apps → New GitHub App)
GitHub App name — будь-що; Control Center (yourname) підійде. Ця назва з’являється на комітах і коментарях, які робить сервер
Homepage URL — будь-що, наприклад https://github.com/your-name
Callback URL — залиште порожнім. У потоку з кодом пристрою його немає
Позначте Enable Device Flow. Це єдине налаштування, без якого вхід не працюватиме
Зніміть позначку Webhook → Active, якщо ви не підключаєте вебхуки окремо
У розділі Repository permissions надайте щонайменше:
- Contents: Read and write
- Metadata: Read-only (обов’язково)
- Pull requests: Read and write
- Issues: Read and write, якщо ви використовуєте GitHub Issues для тікетів, а також для пошуку коментарів бота в розмовах PR (див. Спілкуватися з Control Center з GitHub PR)
- Checks: Read-only, для стану CI на сторінці PR
У розділі Where can this GitHub App be installed? виберіть те, що підходить — «Only on this account» правильно для персонального сервера
Натисніть Create GitHub App

Зберіть три значення

На сторінці застосунку, одразу після створення:

Значення	Де
App ID	Вкладка General, ближче до верху
Client ID	Вкладка General, під «Client secrets»
Private key	Generate a private key — завантажується файл `.pem`

Файл приватного ключа завантажується один раз, і GitHub більше ніколи його не показує. Зберігайте його, доки не вставите; новий можна згенерувати будь-коли.

Секрет клієнта необов’язковий і дає рівно одну річ: якщо залишити «Expire user authorization tokens» увімкненим, саме він непомітно продовжує чийсь токен, а не просить людину входити знову кожні вісім годин. Сам вхід його ніколи не використовує.

Простіше вимкнути це закінчення строку — тоді секрет не потрібен ніде. Якщо ви залишаєте його увімкненим, згенеруйте секрет і вставте його в розділі Налаштування → Сервер → Єдиний вхід (картка Застосунки провайдера) — для нього немає змінної середовища, і в збірку вона не зашита, тож він залишається на вашому сервері.

Установіть його у своєму обліковому записі

Застосунок, який зареєстровано, але не встановлено, може автентифікувати людей і не може прочитати нічого.

На сторінці застосунку відкрийте Install App
Установіть його у своєму обліковому записі або організації
Виберіть All repositories або позначте ті репозиторії, які має бачити цей сервер

Вставте його в Control Center

Перейдіть у Налаштування → Сервер → Єдиний вхід і прокрутіть до картки Застосунки провайдера
У блоці GitHub задайте кожне поле:
- ID застосунку — числовий App ID
- Приватний ключ — вставте весь файл .pem, включно з рядками BEGIN і END
- ID клієнта — з тієї ж сторінки
- Секрет клієнта — лише якщо ви його згенерували (для оновлення токена)
Натисніть Тест

Ключ розбирається під час збереження, тож обрізаний або неправильно відформатований текст відхиляється одразу, а не дає збій у фоновому запиті через години. Тест іде далі й питає в GitHub, на яких облікових записах установлено застосунок, — «збережено» і «працює» — це різні твердження, і лише друге означає, що щось справді запуститься.

Контрольна точка: блок GitHub показує «Сервер може діяти від свого імені, і люди можуть входити.», а рядок GitHub у розділі Налаштування → Робочий простір → Профіль і ідентичність → Хостинг коду тепер пропонує Увійти через GitHub.

Натомість налаштуйте через змінні середовища

Для headless- або сценарного встановлення сервер заповнює кожне поле зі середовища першого разу, коли збереженого значення ще немає:

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

Для них немає прапорців командного рядка — секрет у командному рядку доступний кожному процесу на хості через ps. Середовище — єдине місце, де їх можна задати, і воно має пріоритет над тим, що постачає збірка. .env.template містить повний список.

Для локальної розробки ті самі значення лежать у .env у корені репозиторію, і десктоп передає їх серверу, який запускає. Записуйте ключ там в один рядок: значення в .env — це один рядок, а \n у подвійних лапках перетворюється на переведення рядка.

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

GITHUB_APP_ID і GITHUB_APP_PRIVATE_KEY — ті самі імена, які вже читає брокер токенів пісочниці, тож хост, де вже налаштовано дрібнозернисті токени агентів, отримує можливість входу без додаткових зусиль. Заповнення відбувається один раз на поле — після цього перемагає збережене значення, тож правку в налаштуваннях не скасовує наступний перезапуск.

Зробіть те саме для Linear

У Linear немає потоку з кодом пристрою, тож вхід там — це перехід у браузер і назад, і йому справді потрібен URL зворотного виклику — картка Застосунки провайдера показує, який саме потрібно зареєструвати.

Створіть застосунок OAuth на linear.app/settings/api/applications/new
Укажіть у полі Callback URL той URL, який показує картка, дослівно
Вставте ID клієнта і Секрет клієнта в блок Linear
За потреби додайте API-ключ робочого простору — саме ці облікові дані сервер використовує для синхронізації тікетів, коли ніхто з людей не просив

Усунення несправностей

Діалог входу повідомляє, що провайдер не повернув код пристрою

Enable Device Flow вимкнено в застосунку. Увімкніть його на вкладці General і повторіть спробу.

Тест каже, що облікові дані працюють, але застосунок ніде не встановлено

Реєстрація й установка — окремі кроки. Відкрийте Install App на сторінці застосунку й установіть його.

Тест каже, що приватний ключ не вдалося прочитати

Вставте весь файл .pem, включно з рядками -----BEGIN і -----END. Ключ ed25519 або EC використати не можна — застосунки GitHub підписують через RSA.

Учасник увійшов, але не бачить жодного репозиторію

Застосунок не встановлено на обліковому записі, якому належать репозиторії, або його установка вибирає інші репозиторії. Власний вхід учасника дає лише те, що застосунку дозволено бачити.