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.
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:ManageBranchProtectionto turn it on,git:AddToMergeQueueandgit:RemoveFromMergeQueueto use it, andgit:GetMergeQueueto watch it. - In the Deutsche Cloud Console, also
git:GetRepositoryto 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
- In the repository, choose Settings, then Branch protection.
- In the actions menu of the rule for
main, choose Edit. - Select Require merge queue.
- (Optional) Change Merge method and the other queue settings (see Queue settings).
- Choose Save changes. The rule shows Yes under Merge queue.
dcloud git branch-protection update 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
8a1f3c2d-4b5e-4f60-9a7b-8c9d0e1f2a3b --require-merge-queuePATCH /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/branch-protection/8a1f3c2d-4b5e-4f60-9a7b-8c9d0e1f2a3b
{ "requireMergeQueue": true }resource "dcloud_git_branch_protection" "main" {
repository_id = dcloud_git_repository.this.id
branch_pattern = "main"
require_status_checks = true
require_merge_queue = true
}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
- Open the pull request.
- Choose Merge when ready.
dcloud git merge-queue add 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 7POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/pulls/7/merge-queueNot available in Terraform. Queuing a pull request is an action, not configuration.
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
- The queue builds
ews-readonly-queue/main/pr-<n>-<sha>:main, plus every pull request ahead of it, plus this one, and starts themerge_groupworkflows on it. - When the required checks pass,
mainis fast-forwarded to exactly that commit, and the pull request is marked merged. - 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_queuewebhook), and every build behind it is thrown away and rebuilt without it. Fix it and add it again. A timeout readsRequired 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.