> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gitar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-Merge

> Automatically merge pull requests after Gitar approves them

## Overview

Auto-merge works alongside [Auto-Approve](/features/code-review/auto-approve). When Gitar approves a PR, it also enables your platform's native auto-merge so the PR merges as soon as all other conditions are met, such as passing CI and required approvals.

<CardGroup cols={3}>
  <Card title="Hands-Free Merging" icon="code-merge">
    Approved PRs merge automatically once all checks pass
  </Card>

  <Card title="Platform-Native" icon="shield-check">
    Uses your platform's built-in auto-merge, not a custom queue
  </Card>

  <Card title="Safe by Default" icon="rotate-left">
    Auto-merge is disabled if Gitar later revokes its approval
  </Card>
</CardGroup>

## How It Works

<Steps>
  <Step title="Gitar approves the PR">
    Auto-approve runs after a clean code review. If the PR meets your configured criteria, Gitar submits an approving review.
  </Step>

  <Step title="Auto-merge is enabled">
    Immediately after approving, Gitar enables auto-merge on the PR using your platform's native feature.
  </Step>

  <Step title="The platform merges when ready">
    From here, your platform handles the rest. The PR merges once CI passes, required approvals are in place, and any other branch protection rules are satisfied.
  </Step>
</Steps>

## Prerequisites

Before enabling auto-merge in Gitar, make sure your platform is configured to allow it.

<AccordionGroup>
  <Accordion title="GitHub">
    Enable **Allow auto-merge** in your repository settings under **General**. Without this, Gitar will approve the PR but auto-merge will not be armed.
  </Accordion>

  <Accordion title="GitLab">
    No additional configuration is needed. GitLab uses the project's default merge settings.

    Note: pushing new commits to a GitLab MR cancels the armed auto-merge. If Gitar's next review also approves the MR, auto-merge will be re-enabled automatically.
  </Accordion>
</AccordionGroup>

## Enabling Auto-Merge

Auto-merge is configured alongside auto-approve in your organization settings:

1. Navigate to **Settings** in the Gitar dashboard
2. Open the **Behavior** section
3. Make sure **Auto-approve** is enabled first
4. Enable the **Auto-merge PRs/MRs after auto-approve** toggle
5. On GitHub, select your preferred merge method: **Merge commit**, **Squash**, or **Rebase**

## What Happens If It Fails

If Gitar cannot enable auto-merge, it will post a message in the dashboard comment explaining why. The PR remains approved. Common reasons include:

| Reason                                        | What to do                                               |
| --------------------------------------------- | -------------------------------------------------------- |
| Auto-merge is not allowed for this repository | Enable "Allow auto-merge" in your GitHub repo settings   |
| Gitar lacks merge permission                  | Grant Gitar the necessary permissions in your repository |
| The PR is a draft or has unresolved threads   | Mark the PR as ready and resolve open threads            |

## When Approval is Revoked

If a new push introduces blocking findings, Gitar revokes its approval and disables auto-merge. This prevents the PR from merging while outstanding issues remain.

<Note>
  Auto-merge requires [Auto-Approve](/features/code-review/auto-approve) to be enabled. Gitar only arms auto-merge on PRs it has approved.
</Note>