Настройка интеграции Битрикс24 с GitLab

Настройка интеграции Битрикс24 с GitLab

Разработчики ведут код в GitLab, менеджеры — задачи в Битрикс24. Merge request висит на ревью третий день, а в Б24 задача помечена как «В работе» — менеджер думает, что разработчик ещё пишет код. CI/CD pipeline упал на staging, но об этом узнают только когда QA пишет «ничего не работает». Без связки между GitLab и Б24 две системы живут параллельно, и координация происходит через чат — ненадёжно и медленно.

Архитектура интеграции

Связка работает через GitLab Webhooks и Б24 REST API. GitLab позволяет настраивать webhooks на уровне проекта или группы (Settings → Webhooks). Middleware принимает события, извлекает данные и транслирует их в Б24.

GitLab (push/MR/pipeline) → Webhook → Middleware → Б24 REST API → Задачи/Чат
Б24 (событие задачи) → Webhook → Middleware → GitLab API v4 → Issues/Labels

GitLab webhooks отправляют JSON-payload с заголовком X-Gitlab-Token для аутентификации. Middleware проверяет токен при каждом запросе.

Уведомления в Б24

Middleware маршрутизирует события GitLab в чаты и задачи Б24:

Сообщения форматируются BB-кодами: ссылки на MR, pipeline, коммиты. Для pipeline middleware указывает статус (success, failed, canceled) и длительность.

Привязка merge requests к задачам

Разработчик указывает ID задачи Б24 в описании MR или в названии ветки: feature/B24-2103-payment-gateway. Middleware извлекает ID и связывает MR с задачей.

Жизненный цикл MR отражается в статусе задачи:

1. MR создан → задача переходит в «На ревью». Middleware вызывает tasks.task.update.
2. MR получил approve (Approval Rules) → задача переходит в «Ревью пройдено».
3. MR смёрджен → задача переходит в «Выполнена» или «На тестировании».
4. MR закрыт → задача возвращается в «В работе».

Middleware отслеживает эти события через webhook trigger Merge Request Events и payload-поле object_attributes.action (open, close, merge, approved).

Статус CI/CD в задачах

Pipeline status — одна из ключевых метрик для менеджера. Middleware добавляет информацию о pipeline в задачу Б24:

• Pipeline passed → комментарий в задаче: «CI/CD пройден, коммит {sha}, ветка {ref}». Кастомное поле UF_CI_STATUS = passed.
• Pipeline failed → комментарий с указанием failed-стадии и ссылкой на лог. Уведомление автору коммита в DM.
• Pipeline для MR → статус отображается в комментарии к задаче рядом с информацией о MR.

Для получения деталей о pipeline middleware вызывает GitLab API: GET /api/v4/projects/{id}/pipelines/{pipeline_id}/jobs — список jobs с их статусами и логами.

Синхронизация задач Б24 и GitLab Issues

При необходимости middleware синхронизирует задачи Б24 с GitLab Issues:

GitLab использует scoped labels для workflow — middleware создаёт и назначает метки через PUT /api/v4/projects/{id}/issues/{iid}.

Деплой-трекинг

GitLab Environments и Deployments API дают информацию о том, куда и когда был развёрнут код:

• Webhook Deployment Events содержит environment, status, deployable_url.
• Middleware записывает в задачу: «Развёрнуто на {environment}, URL: {url}».
• Для production-деплоев — отдельное уведомление в канал релизов.

Аутентификация

• GitLab: Project Access Token или Personal Access Token с scope api. Для self-hosted GitLab — тот же механизм, но с кастомным URL.
• Б24: OAuth 2.0 с scope task,im,user.
• Webhook secret token хранится в middleware и проверяется при каждом входящем запросе через заголовок X-Gitlab-Token.

Что внедряем

• Middleware для связки GitLab-проектов с задачами и чатами Б24
• Уведомления о push, merge requests, pipeline и деплоях
• Автоматическое обновление статусов задач по жизненному циклу MR
• Отображение CI/CD-статуса в задачах Б24
• Двустороннюю синхронизацию задач Б24 и GitLab Issues
• Деплой-трекинг с уведомлениями по окружениям