Внешние проверки статуса в запросах на слияние

Внешние проверки статуса позволяют мейнтейнерам проекта отправлять данные запроса на слияние во внешний сервис и использовать ответ сервиса как дополнительное условие слияния. Используйте их, если перед слиянием запрос должен пройти внешнюю проверку соответствия требованиям, контроль качества или проверку безопасности.

Внешние проверки статуса настраиваются отдельно для каждого проекта и не наследуются другими проектами.

Как работают внешние проверки статуса

Когда происходит событие запроса на слияние, Deckhouse Code отправляет информацию о запросе во все внешние сервисы, проверки статуса через которые применяются к целевой ветке. Внешний сервис проверяет запрос на слияние и отправляет результат обратно в Deckhouse Code.

Результат проверки всегда относится к текущему HEAD SHA исходной ветки. Если в запрос на слияние добавлены новые коммиты, предыдущий результат больше не относится к новому состоянию, и Deckhouse Code ожидает новый результат.

Внешние проверки статуса влияют на возможность слияния только если в проекте включена настройка Проверки статуса должны быть успешными. Если настройка выключена, виджет продолжает показывать результаты проверок, но проверки в состоянии с ошибкой или ожидает выполнения не блокируют слияние.

Настройка внешних проверок статуса

Чтобы настроить внешние проверки статуса, откройте проект и перейдите в «Настройки» → «Запросы на слияние».

На странице используются две связанные области настроек:

• «Проверки слияния» — настройки проекта, влияющие на возможность слияния.
• «Внешние проверки статуса» — таблица для создания, обновления и удаления внешних сервисов проверки статуса.

Пользователю нужно право на управление настройками запросов на слияние в проекте. В стандартных ролях оно доступно пользователям с ролью Мейнтейнер или Владелец.

Настройки проверок слияния

Проверки статуса должны быть успешными

Флажок «Проверки статуса должны быть успешными» блокирует запросы на слияние до тех пор, пока все применимые внешние проверки статуса не перейдут в состояние пройдено.

Если флажок выключен, внешние проверки статуса продолжают отображаться в запросах на слияние, но не блокируют слияние.

Тайм-аут проверок статуса

Поле «Тайм-аут проверок статуса» задает тайм-аут по умолчанию для проверок статуса в проекте.

Поведение:

• Значение по умолчанию — 5 минут.
• Значение должно быть 1 минута или больше.
• Значение применяется к проверкам без индивидуального таймаута.
• Если внешний сервис не ответил до истечения таймаута, ответ проверки переходит в состояние с ошибкой.

Таблица внешних проверок статуса

Таблица «Внешние проверки статуса» показывает все сервисы проверки статуса, настроенные в проекте.

В таблице отображаются:

• Название проверки статуса.
• URL внешнего сервиса.
• Область применения по целевым веткам.
• Таймаут проверки или таймаут проекта по умолчанию.
• Состояние общего секрета HMAC.
• Действия «Обновить» и «Удалить».

Если у проверки не задан индивидуальный таймаут, в таблице отображается таймаут проекта с пометкой (по умолчанию).

Добавление внешней проверки статуса

Чтобы добавить внешнюю проверку статуса:

1. Откройте проект.
2. Перейдите в «Настройки» → «Запросы на слияние».
3. В блоке «Внешние проверки статуса» нажмите «Добавить внешнюю проверку статуса».
4. Заполните поля.
5. Нажмите «Новая внешняя проверка статуса».

После создания проверки Deckhouse Code создает ответы в состоянии ожидает выполнения для подходящих открытых запросов на слияние. Запросы во внешний сервис для таких уже существующих запросов на слияние не отправляются. Эти ответы перейдут в состояние с ошибкой после истечения тайм-аута, если пользователь не перезапустит проверку.

Для новых событий запросов на слияние Deckhouse Code автоматически отправляет запросы в подходящие внешние сервисы проверки статуса.

Область применения по веткам

Поле «Целевая ветка» определяет, для каких запросов на слияние используется проверка статуса.

Если целевая ветка запроса на слияние не соответствует области применения проверки, проверка не отображается в виджете запроса на слияние.

Когда целевая ветка меняется, Deckhouse Code пересчитывает применимые проверки. Проверки, которые больше не применяются, удаляются из запроса на слияние, а новые применимые проверки добавляются в состоянии ожидает выполнения.

Общий секрет HMAC

Если задан Общий секрет HMAC, Deckhouse Code добавляет заголовок X-Gitlab-Signature к запросам во внешний сервис.

Значение заголовка — HMAC-SHA256 от тела запроса, сформированный с использованием общего секрета.

Секрет хранится в зашифрованном виде. После сохранения интерфейс показывает только факт наличия секрета. Чтобы заменить секрет:

1. В строке проверки нажмите «Обновить».
2. Нажмите «Изменить секрет».
3. Введите новое значение.
4. Нажмите «Обновить проверку статуса».

Жизненный цикл проверки

Когда происходит событие запроса на слияние, Deckhouse Code отправляет данные запроса на слияние во все применимые внешние сервисы проверки статуса. Данные содержат объект external_approval_rule с id, name и external_url проверки.

Ответ проверки может иметь один из следующих статусов:

Внешний сервис обновляет ответ через API-эндпоинт:

POST /projects/:id/merge_requests/:merge_request_iid/status_check_responses

Запрос должен содержать:

• external_status_check_id — идентификатор проверки статуса.
• sha — текущий HEAD SHA исходной ветки запроса на слияние.
• status — пройдено или с ошибкой.

Deckhouse Code не обновляет ответ, если:

• sha не совпадает с текущим HEAD исходной ветки.
• Ответ больше не находится в состоянии ожидает выполнения.
• Тайм-аут уже истек.

Тайм-ауты

Отсчет тайм-аута начинается в момент отправки запроса во внешний сервис. Если пользователь перезапускает проверку в состоянии с ошибкой, отсчет таймаута начинается с момента перезапуска.

Значение тайм-аута выбирается в следующем порядке:

1. Значение «Тайм-аут в минутах» у проверки статуса.
2. Значение проекта «Тайм-аут проверок статуса».

Фоновый обработчик проверяет ответы в состоянии ожидает выполнения каждую минуту. Когда ответ превышает свой тайм-аут, Deckhouse Code переводит его в состояние с ошибкой и записывает причину Automatically closed after timeout.

Если запрос во внешний сервис завершился ошибкой, Deckhouse Code переводит ответ в состояние с ошибкой и сохраняет причину ошибки. Пользователи могут увидеть причину ошибки в виджете запроса на слияние.

Виджет внешних проверок статуса

Виджет «Внешние проверки статуса» отображается на странице запроса на слияние, если для запроса есть применимые внешние проверки.

Виджет показывает:

• Название проверки.
• Статус проверки.
• URL внешнего сервиса, если ваша роль позволяет его видеть.
• Подробности ошибки для проверок в состоянии с ошибкой, если Deckhouse Code сохранил причину ошибки.
• Действие «Повторить» для проверок в состоянии с ошибкой, если ваша роль позволяет их перезапускать.

Виджет помогает авторам и ревьюерам понять, какие внешние системы еще должны ответить до слияния запроса.

Проверки в состоянии ожидает выполнения

Проверка остается в состоянии ожидает выполнения, пока Deckhouse Code ожидает ответ внешнего сервиса.

Пока хотя бы одна проверка находится в состоянии ожидает выполнения, виджет запроса на слияние обновляет внешние проверки статуса примерно каждые 10 секунд. Опрос останавливается, когда проверок в состоянии ожидает выполнения больше нет.

Проверка в состоянии ожидает выполнения может автоматически перейти в состояние с ошибкой, если внешний сервис не ответит до истечения настроенного тайм-аута. Тайм-аут настраивается на уровне проекта или для конкретной внешней проверки статуса.

Проверки в состоянии с ошибкой

Проверка может перейти в состояние с ошибкой, если:

• Внешний сервис вернул с ошибкой для текущего HEAD SHA запроса на слияние.
• Deckhouse Code не смог отправить запрос во внешний сервис.
• URL внешнего сервиса заблокирован или недоступен.
• Внешний сервис не ответил до истечения тайм-аута.

Если в проекте включена настройка Проверки статуса должны быть успешными, проверка в состоянии с ошибкой блокирует слияние до тех пор, пока проверка не перейдет в пройдено или пока настройки проекта не будут изменены.

Перезапуск проверки в состоянии с ошибкой

Вы можете перезапустить проверку в состоянии с ошибкой, если у вас есть роль Разработчик или выше в проекте.

Перезапуск доступен только для проверок в состоянии с ошибкой, которые относятся к текущему HEAD SHA исходной ветки запроса на слияние.

Чтобы перезапустить проверку в состоянии с ошибкой:

1. Откройте запрос на слияние.
2. Найдите виджет «Внешние проверки статуса».
3. В строке проверки в состоянии с ошибкой нажмите «Повторить».

После перезапуска Deckhouse Code переводит проверку обратно в состояние ожидает выполнения и повторно отправляет текущие данные запроса на слияние во внешний сервис.

Используйте перезапуск после исправления проблемы во внешнем сервисе или если сбой был временным.

URL проверок

Виджет может показывать URL внешнего сервиса для проверки. URL виден только пользователям, роль которых позволяет просматривать URL внешних проверок статуса. В стандартных ролях проекта это доступно пользователям с ролью Разработчик или выше.

Если вы не видите URL, вы все равно можете видеть статус проверки, если ваша роль позволяет смотреть ответы проверок статуса.

Доступ к результатам проверок

Доступ к информации о внешних проверках статуса зависит от роли в проекте:

Для проектов с видимостью внутренний авторизованный пользователь без признака внешнего пользователя может читать ответы внешних проверок статуса в виджете на странице запроса на слияние, если у него есть доступ на чтение данного запроса.

URL внешней проверки при этом отображается только пользователям с правом просмотра URL внешних проверок (в стандартных ролях — Разработчик или выше), поэтому не отображается обычному пользователю, который не является участником проекта.

Удаление внешней проверки статуса

Чтобы удалить проверку:

1. Откройте проект.
2. Перейдите в «Настройки» → «Запросы на слияние».
3. В блоке «Внешние проверки статуса» нажмите «Удалить» для нужной проверки.
4. Подтвердите удаление.

После удаления проверка больше не применяется к запросам на слияние проекта.

События аудита

Deckhouse Code записывает события аудита для управления проверками статуса и изменения ответов.

Устранение неполадок

Запрос на слияние заблокирован внешней проверкой статуса

Проверьте:

• Включен ли флажок «Проверки статуса должны быть успешными».
• Применяется ли проверка к целевой ветке запроса на слияние.
• Отправил ли внешний сервис пройдено для текущего HEAD SHA.
• Не истек ли тайм-аут до обратного вызова внешнего сервиса.

Проверка завершилась в статусе с ошибкой по тайм-ауту

Проверьте:

• Значение проекта «Тайм-аут проверок статуса».
• Индивидуальное значение «Тайм-аут в минутах» у проверки.
• Время ответа внешнего сервиса.
• Нужно ли перезапустить проверку после исправления внешнего сервиса.

Проверка остается в ожидает выполнения

Проверка может оставаться в состоянии ожидает выполнения, пока Deckhouse Code ожидает внешний сервис.

Проверьте:

• Доступен ли внешний сервис.
• Может ли сервис обработать данные запроса на слияние.
• Отправляет ли сервис ответ для текущего HEAD SHA.
• Достаточен ли настроенный тайм-аут для завершения обработки.

Если тайм-аут истечет, проверка перейдет в состояние с ошибкой.

Запрос во внешний сервис завершился ошибкой

Проверьте:

• URL в поле «API для проверки».
• Сетевой доступ от Deckhouse Code до внешнего сервиса.
• Использует ли URL протокол http или https.
• Текст ошибки в виджете запроса на слияние.

Действие Повторить недоступно

Действие «Повторить» отображается только если выполняются все условия:

• Проверка находится в состоянии с ошибкой.
• Проверка относится к текущему HEAD SHA запроса на слияние.
• У вас есть роль Разработчик или выше в проекте.

Если действие «Повторить» недоступно, попросите мейнтейнера проекта проверить настройки проекта и вашу роль.

URL внешнего сервиса не отображается

URL скрыт, если ваша роль не позволяет просматривать URL внешних проверок статуса. Если вам нужен доступ к URL внешнего сервиса, обратитесь к мейнтейнеру проекта.

Ошибка дублирования имени или URL

В проекте не может быть двух внешних проверок статуса с одинаковым «Название сервиса» или «API для проверки». Используйте уникальные значения для каждой проверки.