Use a merge queue

Keep a busy branch green by testing every pull request on top of the branch and everything queued ahead of it.

Last updated 18 November 2026View as Markdown

The branch only ever moves to a commit that passed. It works like GitHub's merge queue. The examples use the repository id 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60, the rule id 8a1f3c2d-4b5e-4f60-9a7b-8c9d0e1f2a3b and pull request 7.

Prerequisites

  • Permission for git:ManageBranchProtection to turn it on, git:AddToMergeQueue and git:RemoveFromMergeQueue to use it, and git:GetMergeQueue to watch it.
  • In the Deutsche Cloud Console, also git:GetRepository to open the repository's pages (without it the page is not found).
  • A branch protection rule for the branch, with Require status checks to pass before merging so the queue has something to wait for.

Step 1: Require the queue

  1. In the repository, choose Settings, then Branch protection.
  2. In the actions menu of the rule for main, choose Edit.
  3. Select Require merge queue.
  4. (Optional) Change Merge method and the other queue settings (see Queue settings).
  5. Choose Save changes. The rule shows Yes under Merge queue.

Step 2: Run your workflow for queue builds

A GitHub Actions workflow adds merge_group next to pull_request, exactly as on GitHub:

on:
  pull_request:
  merge_group:

A workflow in the Deutsche Cloud format uses on: merge_group: the same way.

Step 3: Add a pull request

  1. Open the pull request.
  2. Choose Merge when ready.

If its approvals and checks have passed, it joins the end of the queue at once; if not, it waits and joins as soon as they pass.

Adding is refused with 409 when the pull request is a draft (A draft pull request cannot be queued. Mark it ready first), is not open (Cannot queue a pull request that is merged), targets a branch without the queue (Branch "main" does not require a merge queue, so merge the pull request directly), has lost its source branch, or is already queued (This pull request is already in the merge queue).

Result

  1. The queue builds ews-readonly-queue/main/pr-<n>-<sha>: main, plus every pull request ahead of it, plus this one, and starts the merge_group workflows on it.
  2. When the required checks pass, main is fast-forwarded to exactly that commit, and the pull request is marked merged.
  3. If the build fails, conflicts or times out, the pull request is removed with the reason (on the pull request, on the queue page, in a mail to its author unless the author removed it, and as a merge_queue webhook), and every build behind it is thrown away and rebuilt without it. Fix it and add it again. A timeout reads Required checks did not finish within 60 minutes (…).

Watch a branch's queue on its Merge queue page, linked from a queued pull request (dcloud git merge-queue get 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 --branch main). Remove from queue (DELETE …/pulls/{n}/merge-queue) takes a pull request out; the builds behind it are rebuilt. A pull request also leaves the queue when it is closed or new commits are pushed to it.

While the queue is required, git push to the branch is refused with branch "main" requires a merge queue — add the pull request to the queue instead, and a direct merge with Branch "main" requires a merge queue — add the pull request to the queue instead. A push to an ews-readonly-queue/ branch is refused with branch "…" belongs to the merge queue and is read-only.

Queue settings

These are fields of the branch protection rule; the defaults are GitHub's.

Field Console label Effect Default
requireMergeQueue Require merge queue changes land only through the queue; direct pushes and the merge button are refused false
mergeQueueMethod Merge method merge, squash or rebase: how each pull request is applied in its queue build merge
mergeQueueBuildConcurrency Build concurrency 1–100 queued pull requests built at once 5
mergeQueueMinGroupSize Minimum group size 1–100 pull requests to wait for before the first build and before landing, until the wait time is up 1
mergeQueueMaxGroupSize Maximum group size 1–100 pull requests landed by one fast-forward 5
mergeQueueWaitMinutes Wait time (minutes) 0–360 minutes to wait for the minimum group size 5
mergeQueueCheckTimeoutMinutes Status check timeout (minutes) 1–360 minutes a queue build may wait for its checks before it counts as failed 60
mergeQueueOnlyNonFailing Only merge non-failing pull requests when off, a pull request whose own build failed still lands if a later build containing it passes in its group true

Queue entry states

State Meaning
waiting "merge when ready": waiting for its own approvals and checks; has no place yet
queued in line, not built yet
building its ews-readonly-queue/… branch exists and merge_group checks are running
passed checks passed; lands with its group
failed checks failed, held because a later build may still pass (only-non-failing off)
merged landed; the pull request's merge commit is the commit the branch moved to
removed taken out; removalReason says why

What a queue build sees

Builds use the commit the queue built, so github.event_name is merge_group, github.ref is refs/heads/ews-readonly-queue/<base>/pr-<n>-<sha>, and github.event.merge_group carries head_sha, head_ref, base_sha and base_ref.

Did this page help you?