Налаштування інтеграції Бітрікс24 з GitLab

Налаштування інтеграції Бітрікс24 з GitLab

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

Архітектура інтеграції

Інтеграція працює через GitLab Webhooks та Б24 REST API. GitLab дозволяє налаштовувати вебгуки на рівні проекту або групи (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 — одна з ключових метрик для менеджера. Middleware додає інформацію про pipeline до завдання Б24:

• Pipeline пройдений → коментар у завданні: «CI/CD пройдено, комбіт {sha}, гілка {ref}». Користувацьке поле UF_CI_STATUS = passed.
• Pipeline упав → коментар із указанням упалої стадії та посиланням на лог. Сповіщення автору коміту в 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 з областю api. Для self-hosted GitLab — той же механізм, але з кастомним URL.
• Б24: OAuth 2.0 з областю task,im,user.
• Webhook secret token зберігається в middleware та перевіряється при кожному входящому запиті через заголовок X-Gitlab-Token.

Що ми реалізуємо

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