# 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: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

**Console**
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](#queue-settings)).
5. Choose **Save changes**. The rule shows **Yes** under **Merge queue**.

**CLI**
```sh
dcloud git branch-protection update 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  8a1f3c2d-4b5e-4f60-9a7b-8c9d0e1f2a3b --require-merge-queue
```

**API**
```http
PATCH /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/branch-protection/8a1f3c2d-4b5e-4f60-9a7b-8c9d0e1f2a3b
{ "requireMergeQueue": true }
```

**Terraform**
```hcl
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:

```yaml
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

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

**CLI**
```sh
dcloud git merge-queue add 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 7
```

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/pulls/7/merge-queue
```

**Terraform:** not available. 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

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`.

## Related

- [Merge a pull request](merge-a-pull-request.md)
- [Protect a branch](protect-a-branch.md)
- `git.merge-queue.add` · `dcloud git merge-queue add` · `dcloud_git_branch_protection`
