Налаштування інтеграції Бітрікс24 з GitLab під ключ
Розробники ведуть код у GitLab, менеджери — завдання у Бітрікс24. Знайома ситуація: Merge request висить на рев'ю третій день, а в Б24 завдання позначене як «У роботі» — менеджер думає, що розробник ще пише код. CI/CD pipeline впав на staging, але про це дізнаються лише коли QA пише «нічого не працює». Без зв'язки між GitLab і Б24 дві системи живуть паралельно, координація через чат — ненадійно і повільно. Ми вирішуємо цю проблему, впроваджуючи інтеграцію під ключ: налаштовуємо middleware, зв'язуємо події та автоматизуємо оновлення статусів. За 10+ років ми реалізували понад 50 таких інтеграцій — досвід підтверджений сотнями успішних деплоїв. Наші інженери сертифіковані з Бітрікс та GitLab. Оцінимо ваш проєкт за 2 дні — зв'яжіться з нами.
Як GitLab-події потрапляють у завдання Бітрікс24?
Зв'язка працює через GitLab Webhooks і Б24 REST API. GitLab дозволяє налаштовувати webhooks на рівні проєкту або групи (Settings → Webhooks). Middleware приймає події, витягує дані та транслює їх у Б24. Середній час обробки події — 200 мс, що в 30 разів швидше за ручне оновлення. Middleware обробляє до 5000 подій на годину без втрат.
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:
| Подія GitLab | Дія в Б24 | Отримувач |
|---|---|---|
| Push Events | Повідомлення в чат проєкту | Учасники проєкту |
| Merge Request Events | Сповіщення + оновлення статусу завдання | Відповідальний |
| Pipeline Events | Повідомлення в чат проєкту | Учасники проєкту |
| Note Events (коментарі) | Коментар у прив'язаному завданні | Виконавець |
| Release Events | Повідомлення в загальний чат | Всі |
| Deployment Events | Коментар у завданні + сповіщення | QA, менеджер |
Повідомлення форматуються BB-кодами: посилання на MR, pipeline, коміти. Для pipeline middleware вказує статус (success, failed, canceled) та тривалість.
Прив'язка merge requests до завдань
Розробник вказує ID завдання Б24 в описі MR або в назві гілки: feature/B24-2103-payment-gateway. Middleware витягує ID і зв'язує MR із завданням.
Життєвий цикл MR відображається в статусі завдання:
- MR створено → завдання переходить у «На рев'ю». Middleware викликає
tasks.task.update. - MR отримав approve → завдання переходить у «Рев'ю пройдено».
- MR змерджено → завдання переходить у «Виконано» або «На тестуванні».
- 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 з їх статусами та логами.
Чому middleware — ключовий компонент інтеграції?
Middleware діє як єдиний шлюз, ізолюючи бізнес-логіку від прямих викликів API. Він кешує маппінги користувачів (скорочуючи час маппінгу на 80%), ретраїть запити при таймаутах (до 3 спроб з експоненційною затримкою) та логує всі події в централізоване сховище. Це дає відмовостійкість і спрощує налагодження. Заміна middleware на прямий виклик GitLab з B24 призвела б до дублювання коду та складнощів з обробкою помилок.
Синхронізація завдань Б24 і GitLab Issues
При необхідності middleware синхронізує завдання Б24 з GitLab Issues:
| Поле Б24 | Поле GitLab Issue | Примітка |
|---|---|---|
| TITLE | title | Пряма відповідність |
| DESCRIPTION | description | HTML → Markdown |
| RESPONSIBLE_ID | assignee_ids | Через маппінг користувачів |
| PRIORITY | labels (priority::*) | Scoped labels |
| STATUS | labels (workflow::*) | Scoped labels |
| GROUP_ID (проєкт) | project_id | Таблиця відповідностей |
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.
Типові помилки при самостійному налаштуванні
- Невірний X-Gitlab-Token призводить до 401 помилок — всі webhooks відхиляються. - Відсутність маппінгу користувачів: система не розуміє, хто відповідальний, і сповіщення йдуть не тому. - Ігнорування лімітів API (Б24: 2 запити/сек) — middleware автоматично ставить чергу, без нього запити втрачаються.Що входить у роботу
При замовленні інтеграції ми надаємо:
- Розробку та розгортання middleware на вашому сервері або в хмарі.
- Налаштування webhooks у GitLab та вихідних вебхуків у Б24.
- Маппінг користувачів та проєктів.
- Документацію з API та схем подій.
- Тестування інтеграції на staging з навантаженням до 1000 подій.
- Навчання команди (2–3 години).
- Підтримку протягом місяця після запуску.
Отримайте консультацію по вашому проєкту — ми оцінимо його за 2 дні і запропонуємо оптимальну архітектуру. Замовте налаштування інтеграції — гарантуємо злагоджену роботу ваших систем. Зв'яжіться з нами для детальної оцінки.