# Merge a pull request

Merge, squash or rebase a pull request now, or let auto-merge do it when its approvals and checks pass.

The method is `merge`, `squash` or `rebase`; which ones are allowed is a repository setting (see
[Change repository settings](change-repository-settings.md)). The API and CLI default to `merge`;
the Deutsche Cloud Console preselects the first method the repository allows. The examples use the repository
id `5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60` and pull request 7.

## Prerequisites

- `git:MergePullRequest` on the repository.
- In the Deutsche Cloud Console, also `git:GetRepository` and `git:GetPullRequest` to open the pull request
  (without either the page is not found).
- An open pull request that is not a draft (mark a draft ready first, see
  [Open a pull request](open-a-pull-request.md)) and has no conflicts, with the approvals and code
  owner reviews the target's protection rule requires, and whose required checks passed.
- A target branch that does not require the merge queue (see
  [Use a merge queue](use-a-merge-queue.md)), and a repository that is not a mirror, not being
  imported and not archived.

## Merge it

**Console**
1. Open the pull request. The merge box lists anything that blocks the merge under **Merging is
   blocked**.
2. Choose the method: **Merge commit**, **Squash** or **Rebase** (only the allowed ones are
   shown).
3. Optionally edit the commit message (not for **Rebase**, which keeps the branch's commits).
4. Choose **Merge pull request**. The pull request shows **Merged**.

**CLI**
```sh
dcloud git pulls merge 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 7 --method squash
```

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/pulls/7/merge
{ "method": "squash" }
```

## When a merge is refused

A refused merge answers `409` with the reason, for example:

- `A draft pull request cannot be merged; mark it ready first`
- `Branch "main" requires a merge queue — add the pull request to the queue instead`
- `This repository does not allow rebase merging; use merge commits or squash merging.`
- the approvals or code owner review still missing, for example `Code owners must approve`
- `Status checks have not passed — …` when a rule requires checks and a required one has not
  passed
- a conflict, with the conflicting paths in `conflicts`

Required checks (`requiredChecks` on the rule, or derived) are judged on the pull request's source
commit, from the target branch's workflow files, never from the pull request's; a commit status
whose context is a required check's name satisfies it. See
[Require checks before a merge](/docs/ci-cd-pipeline).

When the target moved, bring the source up to date with `POST …/update-branch`
(`dcloud git branches update-from`, `git:PushRepository`), which merges the target into the source
branch. It answers `This branch is already up to date.` or `Merging the target branch in produces
conflicts.` when there is nothing to do or it cannot.

## Merge automatically

Auto-merge merges the pull request with the chosen method, as you, the moment its approvals and
required checks pass, and right away if they already do.

**Console**
1. Open the pull request, and choose the method.
2. Choose **Enable auto-merge**. The box shows **Auto-merge is on** and the method it will use;
   **Disable auto-merge** turns it off.

**CLI**
```sh
dcloud git pulls enable-auto-merge 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 7 --method squash
```

**API**
```http
PUT /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/pulls/7/auto-merge
{ "method": "squash" }
```

Auto-merge is refused with `409` on a draft (`Mark the draft ready before enabling auto-merge`), on
a pull request that is not open, with a method the repository does not allow, and on a branch that
requires the merge queue, where **Merge when ready** is the equivalent. If you later lose
`git:MergePullRequest` on the repository, auto-merge is turned off rather than run.

## Result

The pull request is `merged` and its commits are on the target branch. With
`deleteBranchOnMerge`, the source branch is deleted, unless it is the default branch, another open
pull request targets it, or its protection rule blocks deletion.

## Related

- [Use a merge queue](use-a-merge-queue.md)
- [Protect a branch](protect-a-branch.md)
- `git.pulls.merge` · `dcloud git pulls merge` · `dcloud git pulls enable-auto-merge`
