 |
Краткое описание | Discourse GitHub Позволяет сотрудникам назначать значки пользователям на основе их вкладов в GitHub. Также позволяет пользователям создавать Linkback-ссылки, постоянные ссылки (Permalinks) и отображать актуальный статус пул-реквестов (PR) в однобусах. |
 |
Руководство по установке | Этот плагин входит в состав ядра Discourse. Отдельная установка плагина не требуется. |
Возможности
Значки GitHub
Назначайте значки своим пользователям на основе их вкладов в GitHub.
Как использовать:
- Включите настройку
github badges enabledв Настройки > Плагины. - Сгенерируйте токен доступа GitHub и вставьте его в настройку
github linkback access token. Инструкции приведены ниже. - Добавьте один или несколько URL-адресов репозиториев GitHub для отслеживания вкладов в настройку сайта
github badges repos.
Как работает подсчёт значков:
Значки учитывают коммиты во всех репозиториях, и когда пользователь вносит вклад в несколько репозиториев, все его коммиты суммируются в общий счётчик.
Значки коммитеров:
| Значок | Требуется коммитов |
|---|---|
| Бронзовый | 1 коммит |
| Серебряный | 25 коммитов |
| Золотой | 1000 коммитов |
Прогрессия значков: По мере накопления вкладов пользователя в любом из отслеживаемых репозиториев он автоматически переходит на следующий уровень значков. Например, если пользователь делает коммит в Репозиторий A, а затем в Репозиторий B, оба вклада учитываются в общем счётчике, позволяя ему перейти от Бронзового к Серебряному, а затем к Золотому.
Linkback GitHub
Создавайте ссылку из пул-реквеста (PR) или коммита GitHub обратно в тему Discourse, где она упоминается.
Как использовать:
- Включите настройку
github linkback enabledв Настройки > Плагины. - Сгенерируйте токен доступа GitHub и вставьте его в настройку
github linkback access token. Инструкции приведены ниже. - Наконец, добавьте проекты, в которые вы хотите отправлять посты, в настройку сайта
github linkback projectsв формате:username/repositoryдля конкретных репозиториевusername/*для всех репозиториев определённого пользователя
Постоянные ссылки GitHub (Permalink)
Заменяйте обычные ссылки GitHub на постоянные ссылки (permalinks).
Как использовать:
- Включите настройку
github permalinks enabledв Настройки > Плагины.
Актуальный статус PR
Отображайте индикаторы актуального статуса для пул-реквестов GitHub в однобусах в постах и сообщениях чата. Статус автоматически обновляется через вебхуки при изменении PR в GitHub.
Типы статуса
| Статус | Цвет | Описание |
|---|---|---|
| Черновик | Серый | PR помечен как черновик |
| Открыт | Серый | PR открыт и ожидает проверки |
| Одобрено | Зелёный | PR одобрен рецензентами |
| Запрошены изменения | Оранжевый | Рецензенты запросили изменения |
| Слит (Merged) | Фиолетовый | PR слит в основную ветку |
| Закрыт | Красный | PR закрыт без слияния |
Как использовать:
Шаг 1: Включение функции
Перейдите в Админ-панель > Настройки > Плагины и установите значение github pr status enabled в true.
Шаг 2: Настройка токенов доступа GitHub
Для получения статуса PR (особенно для частных репозиториев) настройте токены доступа GitHub.
Настройка: github onebox access tokens
Формат:
название_организации|ghp_ваш_токен_здесь
по_умолчанию|ghp_токен_резервный_здесь
Вы можете указать токены для каждой организации, а также токен по_умолчанию, используемый в качестве резервного. Каждая строка должна содержать название_орг|токен, где токен — это Персональный токен доступа GitHub (классический) с областью действия repo.
Пример:
discourse|ghp_xxxxxxxxxxxxxxxxxxxx
my-company|ghp_yyyyyyyyyyyyyyyyyyyy
по_умолчанию|ghp_zzzzzzzzzzzzzzzzzzzzzz
Шаг 3: Настройка вебхуков GitHub (для обновлений в реальном времени)
Чтобы получать автоматические обновления статуса при изменении PR, настройте вебхук в GitHub.
Сгенерируйте секрет вебхука:
openssl rand -hex 32
Установите значение настройки сайта github webhook secret на сгенерированный секрет.
Создайте вебхук в GitHub:
Вы можете создать вебхук на уровне организации (чтобы охватить все репозитории) или для конкретного репозитория.
Для организации:
- Перейдите в Настройки вашей организации
- Перейдите в раздел Webhooks (в разделе Code, planning, and automation)
- Нажмите Add webhook
Для репозитория:
- Перейдите в Настройки вашего репозитория
- Перейдите в раздел Webhooks
- Нажмите Add webhook
Конфигурация вебхука:
| Поле | Значение |
|---|---|
| Payload URL | https://ваш-сайт-discourse.com/discourse-github/webhooks/github |
| Content type | application/json |
| Secret | Ваш сгенерированный секрет вебхука |
| SSL verification | Включить (рекомендуется) |
| Events | Выберите “Let me select individual events” |
Выберите эти события:
- Pull requests
- Pull request reviews
Нажмите Add webhook, чтобы сохранить.
Шаг 4: Проверка настройки
- Создайте тестовый пост с URL-адресом PR GitHub
- Убедитесь, что однобус отображается с иконкой статуса
- Измените статус PR в GitHub (например, одобрите его или закройте)
- В течение нескольких секунд обновите страницу Discourse — статус должен обновиться
Вы можете проверить статус доставки вебхука в настройках вебхуков GitHub, чтобы подтвердить, что события отправляются и принимаются успешно.
Приоритет статуса
Когда у PR есть несколько состояний (например, одобрен, но также запрошены изменения), статус определяется следующим приоритетом:
- Слит (Merged) (наивысший приоритет)
- Закрыт
- Черновик
- Запрошены изменения
- Одобрено
- Открыт (по умолчанию)
Логика статуса рецензии
Функция получает информацию о рецензиях из API GitHub для определения статуса одобрения:
- Берётся последняя рецензия от каждого рецензента
- Состояния “прокомментировано” (commented) и “ожидает” (pending) игнорируются
- Показывается “запрошены изменения”, если любой рецензент запросил изменения
- Показывается “одобрено”, только если есть рецензии и ни одна из них не запрашивает изменения
Где это работает
- Посты форума — Любой пост, содержащий однобус PR GitHub
- Сообщения чата — Однобусы PR в чате также отображают актуальный статус
Примечание: Встроенные однобусы (когда ссылка появляется встроенной в текст, а не как полный предпросмотр) не отображают иконки статуса.
Миграция с компонента темы GitHub Status
Эта функция заменяет компонент темы GitHub Status Indicators. Они несовместимы и не должны использоваться вместе.
Если вы в настоящее время используете компонент темы:
- Отключите и удалите компонент темы
github-status-theme - Включите эту встроенную функцию через настройку
github pr status enabled
Конфигурация
Токен доступа GitHub
Чтобы функция linkback работала, а значки назначались вашим пользователям, вам необходимо предоставить токен доступа GitHub. Вы можете сгенерировать токен здесь: Sign in to GitHub · GitHub.
Для функции linkback требуется область действия public_repo, а для назначения значков область действия не требуется (оставьте всё пустым, если вам нужны только значки). Поскольку область действия public_repo предоставляет права на запись в репозитории, мы рекомендуем создать временный аккаунт GitHub, у которого нет доступа ни к каким репозиториям, и использовать его только для генерации токена.
Области действия токенов по функциям
| Функция | Требуемая область действия |
|---|---|
| Значки | Не требуется |
| Linkback | public_repo |
| Статус PR (публичные репозитории) | Не требуется |
| Статус PR (частные репозитории) | repo |
Справочник настроек сайта
| Настройка | По умолчанию | Описание |
|---|---|---|
enable discourse github plugin |
false |
Главный переключатель плагина |
github badges enabled |
false |
Включить значки за вклад в GitHub |
github badges repos |
(пусто) | URL-адреса репозиториев для отслеживания значков |
github linkback enabled |
false |
Включить linkback из GitHub в Discourse |
github linkback access token |
(пусто) | Токен доступа для функции linkback |
github linkback projects |
(пусто) | Проекты для создания linkback |
github permalinks enabled |
false |
Заменять ссылки GitHub на постоянные ссылки |
github pr status enabled |
false |
Включить иконки статуса PR в однобусах |
github webhook secret |
(пусто) | Секрет для проверки подписи вебхука |
github onebox access tokens |
(пусто) | Токены доступа к API GitHub (формат: org|token) |
Технические детали
Использование API статуса PR
При генерации однобуса PR GitHub Discourse выполняет до двух вызовов API:
- Данные PR:
GET /repos/{owner}/{repo}/pulls/{number}— Получает базовую информацию о PR, включая состояние, статус слияния и статус черновика - Рецензии:
GET /repos/{owner}/{repo}/pulls/{number}/reviews— Получает данные о рецензиях для определения статуса одобрения
Эти вызовы используют ваш настроенный токен доступа, если он доступен, что позволяет получать доступ к частным репозиториям.
Безопасность вебхуков
Запросы вебхуков проверяются с помощью валидации подписи HMAC-SHA256. GitHub подписывает полезную нагрузку вебхука вашим секретом, а Discourse проверяет эту подпись перед обработкой. Недействительные подписи отклоняются с ответом 403.
События вебхуков, вызывающие обновления
- Изменение состояния PR (открыт, закрыт, повторно открыт)
- Слияние PR
- Изменение статуса черновика (превращён в черновик, готов к проверке)
- Отправка рецензий на пул-реквесты
- Редактирование или отмена рецензий
Вопросы производительности
- Повторная обработка (rebaking) ставится в очередь как фоновая задача с низким приоритетом, чтобы не влиять на производительность сайта
- Повторно обрабатываются только посты/сообщения с полными однобусами PR GitHub (встроенные однобусы пропускаются)
- Повторная обработка сообщений чата пропускает уведомления, чтобы избежать дублирования оповещений
ЖУРНАЛ ИЗМЕНЕНИЙ (CHANGELOG)
2025-12-10
- ИСПРАВЛЕНИЕ: Пропуск уведомлений при повторной обработке сообщений чата из вебхуков GitHub
2025-12-09
- ИСПРАВЛЕНИЕ: Пропуск повторной обработки постов с встроенными однобусами PR GitHub
- ИСПРАВЛЕНИЕ: Избегание промежуточного состояния при повторной обработке постов с однобусами
- ИСПРАВЛЕНИЕ: Повторная обработка сообщений чата при изменении статуса PR GitHub
- UX: Использование min-height для предотвращения сдвига макета при изменении иконки статуса
- UX: Уменьшение размера иконки статуса PR GitHub на мобильных устройствах
2025-12-08
- ФУНКЦИЯ: Добавление статуса “запрошены изменения” в однобусы PR GitHub
2025-12-04
- ФУНКЦИЯ: Иконка актуального статуса PR GitHub
2025-11-10
- ФУНКЦИЯ: Разрешённый и запрещённый списки для linkback
2025-11-08
- ФУНКЦИЯ: Добавление списка игнорируемых категорий для linkback GitHub
2024-12-20
- РАЗРАБОТКА: Перемещение discourse-github в ядро (больше не требуется отдельная установка)
Этот плагин теперь включён в ядро Discourse в рамках