Создать GitHub App

Это руководство показывает, как дать вашему серверу собственную идентичность в GitHub. Это занимает около двух минут, делать это должен только владелец сервера, и требуется это один раз на сервер.

Официальная сборка уже поставляется с ID клиента GitHub, поэтому Войти через 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 Apps подписывают с помощью RSA.

Участник вошёл, но не видит ни одного репозитория

Приложение не установлено на аккаунт, которому они принадлежат, либо его установка выбирает другие репозитории. Собственный вход участника даёт только то, что разрешено видеть приложению.