GitHub Actions merge_group: как настроить required checks для merge queue

Зачем merge queue создаёт отдельное событие

Merge queue должна проверить комбинацию изменений, которая фактически попадёт в целевую ветку, а не только каждый pull request по отдельности. Когда PR добавляют в очередь, GitHub формирует merge group и запрашивает для неё проверки. Это отдельный контекст запуска: `GITHUB_SHA` указывает на SHA merge group, а `GITHUB_REF` — на её ref. Поэтому workflow, который реагирует лишь на `pull_request`, не обязан автоматически запуститься для этого SHA. GitHub прямо рекомендует добавить `merge_group` к workflows, чьи checks являются обязательными для защищённой ветки. На практике это означает, что одна и та же тестовая логика должна уметь работать как на PR, так и на временной группе очереди.

Важно: Если merge queue включена, отсутствие `merge_group` в обязательном workflow может выглядеть как «очередь зависла», хотя сам YAML для pull request работает нормально.

Как добавить merge_group в существующий workflow

1. Откройте workflow, который создаёт required check для целевой ветки. Сначала убедитесь, что этот check действительно указан в branch protection или ruleset как обязательный.
2. Сохраните существующий trigger `pull_request` и добавьте рядом `merge_group`. Для явности укажите `types: [checks_requested]` — это текущий тип активности, используемый для запуска проверок merge queue.
3. Не дублируйте jobs только ради события. Пусть один и тот же build/test job выполняется для `pull_request` и `merge_group`, если ему не нужны разные данные.
4. Проверьте условия `if:` и выражения, которые читают `github.event.pull_request.*`. У события `merge_group` payload другой; такие обращения нужно оградить проверкой `github.event_name == 'pull_request'` или заменить более общим контекстом.
5. Добавьте тестовый PR в merge queue и откройте Actions. Убедитесь, что появился отдельный run с событием merge_group и что имя check совпало с тем, которое ожидает правило защиты.
6. После прохождения тестов проверьте, что очередь продвигает PR дальше, а не ждёт check со статусом Expected или Pending.

Минимальный YAML и что в нём важно

Базовая конфигурация обычно содержит два события: `pull_request` с фильтром целевой ветки и `merge_group` с `checks_requested`. Концептуально она выглядит так: `on: { pull_request: { branches: [main] }, merge_group: { types: [checks_requested] } }`. В реальном YAML удобнее записать их отдельными многострочными секциями. Сам job при этом можно не менять, если он делает checkout текущего commit и запускает тесты без привязки к полям PR. Для merge group `actions/checkout` получит именно временный SHA группы. Это то, что нужно: проверяется совокупность изменений в том состоянии, которое очередь собирается слить.

Совет: Если job использует номер PR для комментариев, labels или API-вызовов, отделите эту часть от собственно build/test. На merge_group такие PR-специфичные шаги часто не нужны.

Какие различия учитывать в workflow

• Обычный pull_request. Контекст PR и его поля. Запускать тесты и PR-специфичные шаги
• merge_group. Временный SHA/ref merge group. Запускать required build/test на состоянии очереди
• Условие использует github.event.pull_request. Не универсально для merge_group. Оградить по github.event_name или переработать
• Required check не появился. Очередь ждёт обязательный статус. Проверить trigger, имя job/check и ruleset

Почему check может оставаться Expected или Pending

Первая причина — workflow вообще не подписан на `merge_group`. Вторая — событие приходит, но job пропускается из-за условия, рассчитанного только на `pull_request`. Третья — ruleset ждёт check с другим именем: например, после рефакторинга изменили `jobs.<id>.name`, а правило осталось прежним. Четвёртая — матрица или reusable workflow создают набор checks, из которого обязательным назначено имя, не возникающее в новом сценарии. Диагностику лучше вести от очереди назад: посмотреть, какой check она ждёт, затем найти соответствующий run и убедиться, что нужный job действительно создан. Не следует лечить проблему снятием required check, если причина лишь в trigger.

Чек-лист перед включением в основной репозиторий

• В workflow одновременно присутствуют `pull_request` и `merge_group`.
• Для `merge_group` используется `checks_requested`.
• Build/test не требует полей `github.event.pull_request` без защитного условия.
• Checkout тестирует текущий SHA события, а не вручную подставленный SHA головы PR.
• Имя required job совпадает с check, указанным в branch protection или ruleset.
• Тестовый PR успешно проходит именно через merge queue, а не только обычный PR run.
• PR-специфичные побочные действия не выполняются на merge_group без явной необходимости.

Когда merge_group не нужен

`merge_group` не требуется только потому, что в репозитории есть pull requests. Он нужен именно для workflows, которые должны запускаться при создании merge group, в первую очередь для required checks, используемых merge queue. Если очередь не включена или конкретный workflow не участвует в обязательной проверке, добавление события может лишь создать лишние CI-запуски. Отдельно не путайте merge queue с обычным авто-merge: авто-merge может ждать стандартные проверки PR, тогда как merge queue формирует собственную группу и требует проверки этого состояния. Поэтому сначала определите, какой механизм слияния реально включён в репозитории, и уже затем расширяйте triggers.

Предупреждение: Добавляйте `merge_group` адресно в те CI-workflows, статус которых действительно нужен очереди.

Как проверить настройку без риска для основной ветки

После изменения YAML создайте небольшой тестовый PR, дождитесь обычных required checks и добавьте его в merge queue. В Actions должны быть видны два разных контекста: ранее выполненный PR run и новый run на событии merge_group. Сверьте event name, SHA и итоговый check. Если в очереди несколько PR, временная группа может пересобираться при изменении состава очереди, поэтому повторный запуск сам по себе не является ошибкой. Важно, чтобы каждый актуальный merge group получал обязательные статусы и чтобы workflow не зависел от данных, существующих только у исходного PR.

Что учитывать

Базовая конфигурация обычно содержит два события: `pull_request` с фильтром целевой ветки и `merge_group` с `checks_requested`. Концептуально она выглядит так: `on: { pull_request: { branches: [main] }, merge_group: { types: [checks_requested] } }`. В реальном YAML удобнее записать их отдельными многострочными секциями. Сам job при этом можно не менять, если он делает checkout текущего commit и запускает тесты без привязки к полям PR. Для merge group `actions/checkout` получит именно временный…

Источники и проверка

Фактическая часть сверена по первичным источникам (в т.ч. Events that trigger workflows). Пример и формулировки — редакция N1RO на 2026-09-21.

• Events that trigger workflows
• Troubleshooting required status checks — merge queue