Setting up Bitrix24 integration with GitLab

Setting up Bitrix24 Integration with GitLab

Developers keep code in GitLab, managers keep tasks in Bitrix24. A merge request has been under review for three days, but in B24 the task is marked "In Progress" — manager thinks the developer is still writing code. CI/CD pipeline failed on staging, but nobody finds out until QA writes "nothing works." Without a link between GitLab and B24, the two systems live in parallel, and coordination happens through chat — unreliable and slow.

Integration Architecture

The integration works through GitLab Webhooks and B24 REST API. GitLab allows configuring webhooks at the project or group level (Settings → Webhooks). Middleware receives events, extracts data, and translates them to B24.

GitLab (push/MR/pipeline) → Webhook → Middleware → B24 REST API → Tasks/Chat
B24 (task event) → Webhook → Middleware → GitLab API v4 → Issues/Labels

GitLab webhooks send JSON payload with X-Gitlab-Token header for authentication. Middleware checks the token on each request.

Notifications to B24

Middleware routes GitLab events to B24 chats and tasks:

Messages are formatted with BB-codes: links to MR, pipeline, commits. For pipeline, middleware indicates status (success, failed, canceled) and duration.

Linking Merge Requests to Tasks

A developer specifies the B24 task ID in the MR description or in the branch name: feature/B24-2103-payment-gateway. Middleware extracts the ID and links the MR to the task.

MR lifecycle is reflected in task status:

1. MR created → task moves to "Under Review." Middleware calls tasks.task.update.
2. MR gets approve (Approval Rules) → task moves to "Review Passed."
3. MR merged → task moves to "Completed" or "Testing."
4. MR closed → task returns to "In Progress."

Middleware tracks these events via webhook trigger Merge Request Events and payload field object_attributes.action (open, close, merge, approved).

CI/CD Status in Tasks

Pipeline status is one of the key metrics for a manager. Middleware adds pipeline information to B24 task:

• Pipeline passed → comment in task: "CI/CD passed, commit {sha}, branch {ref}." Custom field UF_CI_STATUS = passed.
• Pipeline failed → comment with failed stage and log link. Notification to commit author in DM.
• Pipeline for MR → status shown in task comment alongside MR info.

For pipeline details, middleware calls GitLab API: GET /api/v4/projects/{id}/pipelines/{pipeline_id}/jobs — list of jobs with statuses and logs.

Syncing B24 Tasks and GitLab Issues

When needed, middleware syncs B24 tasks with GitLab Issues:

GitLab uses scoped labels for workflow — middleware creates and assigns labels via PUT /api/v4/projects/{id}/issues/{iid}.

Deploy Tracking

GitLab Environments and Deployments API provide information about where and when code was deployed:

• Webhook Deployment Events contains environment, status, deployable_url.
• Middleware writes to task: "Deployed to {environment}, URL: {url}."
• For production deploys — separate notification to releases channel.

Authentication

• GitLab: Project Access Token or Personal Access Token with scope api. For self-hosted GitLab — same mechanism with custom URL.
• B24: OAuth 2.0 with scope task,im,user.
• Webhook secret token is stored in middleware and checked on each incoming request via X-Gitlab-Token header.

What We Implement

• Middleware connecting GitLab projects to B24 tasks and chats
• Notifications about push, merge requests, pipeline, and deploys
• Automatic task status updates across MR lifecycle
• CI/CD status display in B24 tasks
• Bidirectional sync between B24 tasks and GitLab Issues
• Deploy tracking with environment-specific notifications