Документация

Деплои GitLab

Версия v2.5.1 · Обновлено

Деплои 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
42productionPlatformAPI, Worker
42stagingPlatformAPI staging
73productionPlatformDatabase

Сопоставление точное, с учётом регистра; маски не используются. Одинаковую пару «проект + окружение» нельзя задать дважды: выберите все её сервисы в одном правиле. Несовпавшие события получают 200 с status: ignored и reason: no_matching_mapping, без создания изменения. Пустой список правил отключает приём новых деплоев через этот URL.

В выборе сервисов показаны действующие разрешения changed. Настройка маппинга не выдаёт прав: при каждой новой записи сервер проверяет текущие разрешения, активность сервисов, команды, источника и интеграции. Удалённое разрешение может сделать существующий маппинг недействительным; измените его или восстановите нужное разрешение. Отозвать доступ полностью можно отключением источника или токена.

3. Настройте GitLab#

Откройте проект → Settings → Webhooks → Add new webhook:

ПолеЗначение
URLСкопируйте URL вебхука из редактора источника IR
Secret tokenТокен интеграции IR из предыдущего шага
TriggerDeployment 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.