Продвинутая интеграция GitHub + Пачка

Скрипт: Расширенное оповещение о статусах Pull Request в теле сообщения и треде
Язык: TypeScript
Cложность: Высокая
Автор: Павел Голубев, frontend lead
Репозиторий: https://github.com/pachca/review-bot

‍

Интеграция позволит соединить ваш репозиторий GitHub, таск-трекер команды и Пачку. Вы всегда будете знать статусы задач и сможете быстро обсуждать их в тредах.

‍

Описание интеграции

Когда в вашем репозитории появляется новый Pull Request (PR), бот Пачки создает сообщение в чате со статусом и автором.

Все важные изменения в PR отображаются в треде и обновляют статус в родительском сообщении.

‍

Используйте одинаковые никнеймы в github и Пачке, тогда в сообщениях от бота будут подсвечиваться правильные профили в Пачке.

‍

Что подсвечивается в основном (родительском) сообщении

• Название Pull Request
• Ссылка на GitHub
• Ccылка на задачу в таск-трекере (в данном примере прикрепляется ссылка на Linear, вы можете изменить его на любой другой сервис. Например, на Jira или Asana)
• Ник автора Pull Request
• Статус задачи (🏗️ В работе, 🧑‍🍼 Ожидает первого ревью, 👌 Заапрувлено, 🎉 Смержен, ❌ Закрыт)

Какие статусы подсвечиваются в треде под сообщением

• 🆕 @name создал PR
• ✏️ @name запросил правки
• 📣 @name1 запросил ревью от @name2
• 📣 @name отметил себя ревьюером
• 👏 @name заапрувил
• 🏗️ @name сделал rebase
• 🎉 @name смержил PR
• 🏗️ @name отредактировал заголовок Cтарое название задачи -> Новое название задачи
• 🩹 Ошибка CI - #number_task @name
  ‍↳ Lint helpers
  ‍↳ Typecheck

‍

Этап 1. Создайте бота в Пачке

1. Перейдите в раздел «Автоматизации» → «Интеграции»
2. Откройте в раздел «Чат-боты и вебхуки»
3. Создайте нового бота, используя иконку "+”. Затем придумайте боту название и аватарку
4. Скопируйте access_token бота, это можно сделать во вкладке «API» в настройках бота
5. Добавьте бота в чат, в котором вы хотите получать уведомления о Pull Request. Для этого внутри чата нажмите “Информация о чате” → “Интеграции” → “Добавить интеграцию”
6. Запишите chat_id, он понадобится при размещении на сервере (этап 5).
   Chat_id можно найти в адресной строке Web-версии Пачки. Например, у чата https://app.pachca.com/chats/8458483 id будет 845848

‍

Этап 2. Включите вебхуки в github репозитории

1. Перейдите в репозиторий → Settings → Webhooks → Add webhook
2. Укажите url, на который будут приходить вебхуки. О том, как получить url, рассказали в блоке про размещение интеграции на сервере (этап 5)
3. Укажите Content type: application\json
4. Выберите “Let me select individual events” и отметьте чек-боксами:
   1. Pull requests
   2. Pull request reviews
   3. Workflow runs

Подробная документация github по настройке вебхуков

‍

Этап 3. Получите токен авторизации в Github REST API

Pull Request и Тред Пачки должны быть связаны между собой. Для этого интеграция отправляет комментарий со ссылкой на тред Пачки при создании PR.

• Убедитесь, что в организации разрешено использовать fine-grained personal access tokens
• Создайте нового пользователя с доступом к нужному репозиторию. Дайте ему имя, например, "Бот Пачки". В настройках этого пользователя создайте fine-grained personal access token для нужного репозитория организации
• Среди repository permissions выберите
  • Actions (Read-only)
  • Pull Requests (Read and write)
• Сохраните токен и логин пользователя. Эти данные понадобятся при конфигурации

Подробная документация github по способам авторизации REST API

‍

Этап 4. Скачайте код интеграции или модифицируйте и соберите свою версию

Репозиторий: https://github.com/pachca/review-bot

В разделе releases лежит готовый index.js файл для node18+, который будет работать в облачной функции Яндекс

Также вы можете отредактировать index.ts под свои нужны и собрать файл самостоятельно.

bun i
bun run build

Используйте bun вместо npm\node, чтобы работать напрямую c index.ts без этапа сборки.

‍

Этап 5. Разместите интеграцию на сервере

Вариант 1. Размещение на облачных функциях Яндекс

При выборе этого способа не нужно будет поддерживать работу собственного сервера. Яндекс Облако предоставляет бесплатно 1млн вызовов функции в месяц, что более чем достаточно для бота.

1. Воспользуйтесь инструкцией по созданию функции
2. Добавьте файл index.js в вашу функцию
3. Точка входа index.handler
4. Добавьте переменные окружения для функции
   1. GITHUB_ACCESS_TOKEN - access_token пользователя с доступом к репозиторию и rest-api
   2. GITHUB_USER_LOGIN - логин пользователя в github, чей access_token вы получили
   3. GITHUB_OWNER - название организации. Например, для текущего репозитория https://github.com/pachca/review-bot - это pachca
   4. GITHUB_REPO - название организации. Например, для текущего репозитория https://github.com/pachca/review-bot - это review-bot
   5. PACHCA_API_ACCESS_TOKEN - access_token бота в Пачке
   6. PACHCA_CHAT_ID - чат Пачки, в котором будут создаваться сообщения. Бот должен быть участником этого чата.
5. Сохраните изменения
6. В разделе "Обзор" функции сделайте ее публично
7. Затем скопируйте Ссылку для вызова и укажите ее в вебхуках репозитория

Вариант 2. Размещение на своем сервере

Переместите содержимое module.exports.handler внутрь функции вашего веб-сервера и замените возвращаемые ответы на подходящий формат.

‍

Примечания к скрипту

Постарались сделать удобный гайд для того, чтобы вы смогли быстро настроить интеграцию с Github в Пачке. Актуальный ReadMe можно всегда найти в репозитории https://github.com/pachca/review-bot

Если вдруг что-то не получилось, описание непонятно или хотелось бы увидеть дополнительные функции в интеграции, то мы всегда будем рады пообщаться с вами, чтобы улучшить инструкцию.

Для этого напишите нашей команде поддержки в Телеграм бот