Интеграция с GitHub

Подключите учетную запись или организацию GitHub один раз в разделе Settings → GitHub. После этого любой pull request, в названии ветки, заголовке или описании которого есть идентификатор задачи (например, MUL-123), будет автоматически связан с этой задачей, появится в разделе Pull requests на боковой панели задачи, а при слиянии (merge) PR задача автоматически перейдет в статус Done.

Вам не нужно настраивать каждую задачу отдельно. Весь процесс управляется через идентификаторы.

Что делает эта интеграция

Зеркалируется только сам PR. Коммиты, ссылки на ветки без открытого PR и состояния проверок CI не обрабатываются. Интеграция намеренно ограничена в функциональности.

Как происходит поиск идентификаторов

Вебхук извлекает идентификаторы из трех полей в следующем порядке: название ветки PR, заголовок PR, описание PR. Алгоритм сопоставления:

• Не учитывает регистр — mul-123, MUL-123, Mul-123 будут распознаны как один и тот же идентификатор.
• Ограничен — использование \b слева и границы цифр справа предотвращают захват номеров версий, таких как v1.2-3 или строк в формате email.
• В рамках рабочего пространства — сопоставляется только с префиксом задач данного пространства. FOO-1 в пространстве с префиксом MUL будет проигнорирован, даже если числовой идентификатор совпадает.
• Дедупликация — упоминание MUL-1, MUL-1 в описании приведет к созданию связи только один раз.

В одном PR можно ссылаться на несколько задач. Closes MUL-1, MUL-2 свяжет PR с обеими задачами, и их слияние переведет обе задачи в статус Done.

Правило автоперевода в статус Done

Когда поле merged у PR принимает значение true, оценивается каждая связанная задача:

Закрытие PR без слияния лишь обновляет статус карточки PR на Closed. Связанные задачи остаются в прежних статусах — пользователь сам решает, что означает закрытие без слияния.

Что не связывается автоматически

• Идентификаторы в сообщениях коммитов — сканируются только ветки, заголовки и описания PR. Коммит с заголовком MUL-123: fix login не будет автоматически связан, если эта же строка не появится в заголовке или описании PR.
• Идентификаторы в комментариях к PR — сканируются только метаданные самого PR; последующие комментарии в GitHub игнорируются.
• PR в репозиториях, где не установлено приложение — без установленного приложения Предиктор Икс не получает вебхуки.
• Ручная привязка PR к задаче — интерфейса для этого пока нет. Если ваш процесс подразумевает использование идентификаторов там, где Предиктор Икс их не ищет, добавьте их в заголовок или описание PR.

Отключение

В разделе Settings → GitHub нет списка установленных приложений — вы управляете существующими установками напрямую через GitHub:

• Через GitHub — удалите приложение Предиктор Икс GitHub по адресу https://github.com/settings/installations (для личных аккаунтов) или https://github.com/organizations/<org>/settings/installations (для организаций). Предиктор Икс получит вебхук installation.deleted и удалит соответствующие данные в реальном времени; любая открытая страница настроек обновится без перезагрузки.
• Отключение внутри Предиктор Икс доступно только администраторам — элемент управления отключением на вкладке GitHub скрыт для обычных пользователей. Он остается доступным, даже если главный переключатель GitHub выключен, чтобы администраторы могли отозвать устаревшую установку после отключения функции.

После отключения зеркалированные записи PR остаются в базе данных, чтобы история в боковых панелях задач сохранялась, но новые события вебхуков от этой установки приниматься не будут.

Права доступа и видимость

• Подключение / отключение требуют прав владельца или администратора рабочего пространства. Участники видят описание карточки, но кнопки подключения нет.
• Боковая панель Pull requests в задаче видна всем, у кого есть доступ к чтению задачи — права доступа аналогичны правам на просмотр деталей задачи.
• Приложение GitHub запрашивает доступ только на чтение pull request'ов и метаданных. Предиктор Икс не вносит коммиты, комментарии или статусы проверок обратно в GitHub.

Настройка собственного сервера (Self-host)

Если вы используете Предиктор Икс Cloud, интеграция уже настроена — пропустите этот раздел.

Для установки на свой сервер вам нужно создать одно приложение GitHub, направить его на свой сервер и задать две переменные окружения. Весь процесс описан ниже.

1. Создание приложения GitHub

Перейдите по одной из ссылок:

• Личный аккаунт → https://github.com/settings/apps/new
• Организация → https://github.com/organizations/<org>/settings/apps/new

Заполните поля:

После Create GitHub App сохраните два значения со страницы приложения:

• Public link вверху — часть ссылки после последнего слэша является slug. https://github.com/apps/predictorx-acme → slug = predictorx-acme.
• Webhook secret, который вы только что сгенерировали (GitHub не позволит прочитать его позже — сохраните сейчас).

2. Настройка переменных окружения

На сервере API:

GITHUB_APP_SLUG=predictorx-acme
GITHUB_WEBHOOK_SECRET=<webhook secret, который вы сгенерировали>

# Опционально, но рекомендуется — заполняет имя аккаунта сразу при
# установке, не дожидаясь первого вебхука:
GITHUB_APP_ID=<числовой ID приложения со страницы настроек>
GITHUB_APP_PRIVATE_KEY=<полный PEM-блок, включая BEGIN/END строки>

GITHUB_APP_SLUG и GITHUB_WEBHOOK_SECRET обязательны. Если хотя бы одно отсутствует:

• Кнопка Connect GitHub в настройках будет неактивна с подсказкой "не настроено".
• Эндпоинт /api/webhooks/github будет возвращать 503 github webhooks not configured — Предиктор Икс отклоняет события без секрета, вместо того чтобы ошибочно считать любую подпись валидной.

GITHUB_APP_ID и GITHUB_APP_PRIVATE_KEY опциональны. Они позволяют при установке получать реальное имя организации или пользователя через эндпоинт GitHub /app/installations/{id}. Без них карточка подключения будет кратко показывать Connected to unknown, пока GitHub не доставит вебхук installation.created (обычно через несколько секунд). Сгенерируйте закрытый ключ в разделе Private keys → Generate a private key на странице настроек приложения; вставьте весь PEM-блок (включая строки -----BEGIN/END RSA PRIVATE KEY-----) в переменную окружения, сохраняя переносы строк.

FRONTEND_ORIGIN также должен быть задан; колбэк настройки после установки перенаправит пользователя на <FRONTEND_ORIGIN>/settings?tab=github.

После изменения переменных окружения перезапустите API.

3. Выполнение миграций

Интеграция использует таблицы из миграции 079_github_integration. При обновлении старой версии:

make migrate-up

Будут созданы три таблицы: github_installation, github_pull_request, issue_pull_request. Они настроены на каскадное удаление вместе с рабочим пространством.

4. Подключение через UI

В Предиктор Икс:

1. Откройте Settings → GitHub как владелец или администратор.
2. Нажмите Connect GitHub. Откроется вкладка GitHub.
3. Выберите репозитории, которым нужно дать доступ, и нажмите Install.
4. GitHub перенаправит вас на <api-host>/api/github/setup, который запишет установку и вернет вас на <FRONTEND_ORIGIN>/settings?tab=github&github_connected=1.

После этого откройте любой PR, в названии ветки/заголовке/описании которого есть идентификатор задачи — через несколько секунд на странице задачи появится блок Pull requests.

5. Проверка через curl

Если на странице Recent Deliveries в GitHub после установки отображается 401 invalid signature, значит секреты не совпадают. Самый быстрый способ проверить, где ошибка:

SECRET="<значение из GITHUB_WEBHOOK_SECRET>"
BODY='{"zen":"test"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')
curl -i -X POST https://<api-host>/api/webhooks/github \
  -H "X-Hub-Signature-256: sha256=$SIG" \
  -H "X-GitHub-Event: ping" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Ограничения

Несколько нюансов, которые стоит учитывать сейчас:

• Нет UI для ручной связи — единственный способ связать PR — это наличие идентификатора в ветке, заголовке или описании.
• Нет CI / статуса проверок — зеркалируется только сам PR. Статус сборки, комментарии ревьюеров и список проверяющих в Предиктор Икс не отображаются.
• Нет настроек правила merge → Done на уровне пространства — это фиксированное правило (слияние → Done, если не cancelled). Возможность настройки — задача на будущее.
• Логика для нескольких PR на одну задачу консервативна — если два PR ссылаются на MUL-123 и первый из них слит, задача сразу переходит в Done. Доработка, ожидающая завершения всех связанных PR, находится в разработке.

Дальнейшие шаги

• Задачи — идентификаторы задач (MUL-123), упоминаемые в PR
• Рабочие пространства — где задается префикс задач для конкретного пространства
• Переменные окружения — полная справка по env-переменным, включая переменные для GitHub