Деплои GitLab → Change Intelligence#
GitLab отправляет стандартные Deployment events. IR создаёт изменение, связывает его с настроенными сервисами и обновляет состояние по событиям деплоя. Добавлять curl в pipeline или менять JSON вебхука не требуется.
1. Подготовьте интеграцию в IR#
Фоновая обработка изменений в Администрирование → Системные настройки.
команду-владельца. Первый источник создаётся автоматически.
Изменённый сервис на каждый нужный сервис либо на целевую команду целиком.
Деплои GitLab нажмите Добавить (подсказка «Добавить маппинг»).
и выберите один или несколько сервисов IR. Сохраните источник.
полностью он показывается только при выпуске.
- Глобальный администратор включает Приём Change Events и
- В Интеграции изменений создайте интеграцию, выбрав группу и
- На вкладке Разрешения добавьте для этого источника разрешение
- На вкладке Источники выберите Изменить источник. В разделе
- Укажите ID проекта GitLab, точное имя окружения, например
production, - На вкладке Токены выпустите токен интеграции и сохраните его:
Используйте один источник для одного экземпляра GitLab. ID проектов и деплоев у разных экземпляров могут совпадать. Для другой команды-владельца создайте другой источник. В интеграции группы все команды и сервисы должны принадлежать этой группе; глобальный администратор также может управлять центральной интеграцией.
2. Как определяется команда и сервисы#
GitLab не должен знать ID команд и сервисов IR. Команда-владелец изменения берётся из выбранного источника. Поля project.id и environment входящего события сопоставляются с правилами источника:
| Проект GitLab | Окружение | Команда-владелец источника | Изменяемые сервисы IR |
|---|---|---|---|
| 42 | production | Platform | API, Worker |
| 42 | staging | Platform | API staging |
| 73 | production | Platform | Database |
Сопоставление точное, с учётом регистра; маски не используются. Одинаковую пару «проект + окружение» нельзя задать дважды: выберите все её сервисы в одном правиле. Несовпавшие события получают 200 с status: ignored и reason: no_matching_mapping, без создания изменения. Пустой список правил отключает приём новых деплоев через этот URL.
В выборе сервисов показаны действующие разрешения changed. Настройка маппинга не выдаёт прав: при каждой новой записи сервер проверяет текущие разрешения, активность сервисов, команды, источника и интеграции. Удалённое разрешение может сделать существующий маппинг недействительным; измените его или восстановите нужное разрешение. Отозвать доступ полностью можно отключением источника или токена.
3. Настройте GitLab#
Откройте проект → Settings → Webhooks → Add new webhook:
| Поле | Значение |
|---|---|
| URL | Скопируйте URL вебхука из редактора источника IR |
| Secret token | Токен интеграции IR из предыдущего шага |
| Trigger | Deployment events |
| SSL verification | Включена; сертификат IR должен быть доверенным для GitLab |
| Custom webhook template | Оставьте пустым: нужен стандартный payload |
URL имеет вид https://ir.example.com/api/change-events/gitlab/12, где 12 — ID источника, а не интеграции, команды или проекта. При использовании внешнего reverse proxy проверьте, что скопированный адрес доступен серверу GitLab. Токен передаётся стандартным заголовком X-Gitlab-Token. Можно использовать Authorization: Bearer, но если отправляются оба заголовка, их токены должны совпадать. Signing token GitLab здесь не заменяет Secret token: проверка HMAC этим endpoint не выполняется.
Job должна создавать deployment в GitLab: обычно это job с настроенным environment. Одного успешного pipeline или push недостаточно для Deployment event. Для группового webhook, если он доступен в вашей редакции GitLab, можно добавить правила нескольких проектов в один источник.
GitLab должен иметь сетевой доступ к IR. В закрытом контуре учитывайте настройки GitLab для исходящих webhook в локальную сеть. Отправитель — сервер GitLab, поэтому доступ только от Runner недостаточен.
4. Проверьте результат#
Запустите деплой или используйте Test → Deployment events в GitLab. Тестовое событие обрабатывается как настоящее: проект и окружение должны соответствовать настроенному правилу. В Recent events проверьте ответ:
| HTTP | Значение |
|---|---|
| 201 | Новое событие принято |
| 200 | Повтор уже принятого события либо событие без подходящего правила; смотрите тело ответа |
| 401 | Нужен действующий токен интеграции; JWT и личный API-токен не подходят |
| 403 | Нет доступа к источнику или сервису; проверьте активность и разрешения |
| 404 | Приём изменений выключен либо неверный URL |
| 409 | Под той же идентичностью события пришло другое содержимое или конфликтует состояние |
| 413 / 422 | Слишком большой запрос / неверные поля, тип события или время |
| 429 / 503 | Лимит или временная занятость; повторите доставку с учётом Retry-After |
Откройте Операции → Изменения. В карточке будут команда, сервисы, окружение, состояние и ссылка на job, если она была в событии. Отдельная настройка автокорреляции сервиса определяет, будут ли изменения предлагаться для его алертов.
Состояния и повторная доставка#
running, success, failed, canceled преобразуются в change.started, change.succeeded, change.failed, change.cancelled. blocked, approved и rejected сохраняются как change.updated: ожидание или решение согласующего не подменяет итог деплоя. Неизвестный статус возвращает 422.
Один deployment определяется источником, ID проекта и deployment_id. Событие дополнительно определяется статусом и status_changed_at. Используется время GitLab с часовым поясом, а не время получения запроса. События могут приходить не по порядку. Повторная доставка того же нормализованного события не создаёт дубль, не увеличивает ревизию и не переносит принятое событие на другие сервисы после изменения правил. Ротация токена не меняет идентичность.
GitLab-источник работает с порядком timestamp. Общий API POST /api/change-events продолжает принимать прежний стандартизированный JSON. Для настройки через API поле gitlab_mappings в PATCH источника выглядит так:
{
"expected_revision": 7,
"gitlab_mappings": [
{"project_id": 42, "environment": "production", "service_ids": [10, 11]}
]
}
expected_revision берите из текущего auth_revision интеграции. Пропущенное поле сохраняет правила, [] очищает их. Допускается до 100 правил, до 100 сервисов на правило. Остальные лимиты совпадают с общим приёмом изменений.
См. также: Deployment events GitLab и настройка webhooks.