Skip to main content

​
Overview

Auto-merge works alongside 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. Not every host has a native auto-merge to arm. See Platform Support.

Hands-Free Merging

Approved PRs merge automatically once all checks pass

Platform-Native

Uses your platform’s built-in auto-merge, not a custom queue

Safe by Default

Auto-merge is disabled if Gitar later revokes its approval

​
How It Works

1

Gitar approves the PR

Auto-approve runs after a clean code review. If the PR meets your configured criteria, Gitar submits an approving review.
2

Auto-merge is enabled

Immediately after approving, Gitar enables auto-merge on the PR using your platform’s native feature.
3

The platform merges when ready

The PR merges once CI passes and required approvals and branch protection rules are satisfied. If every requirement is already satisfied, the reviewed change can merge immediately.

​
Prerequisites

Before enabling auto-merge in Gitar, make sure your platform is configured to allow it.
Enable Allow auto-merge in your repository settings under General. Without it, Gitar approves the PR but auto-merge is not armed.
No additional configuration is needed. GitLab uses the project’s default merge settings.Pushing new commits to a GitLab MR cancels the armed auto-merge. If Gitar’s next review also approves the MR, auto-merge is re-enabled automatically.
Gitar enables Azure DevOps auto-complete using the connected service account. Azure DevOps completes the PR when its merge policies are satisfied, including immediately if it is already ready to merge.

​
Enabling Auto-Merge

Auto-merge is configured alongside auto-approve in your organization settings:
  1. Navigate to Settings -> Configuration in the Gitar dashboard
  2. Open the Behavior section
  3. Make sure Auto-approve is enabled first
  4. Enable the Auto-merge PRs toggle
  5. On GitHub or Azure DevOps, select the merge method: Merge commit, Squash, or Rebase

​
Auto-Merge Criteria

By default every auto-approved PR is armed for merge. Criteria narrow that down. Write them in plain language in Settings -> Configuration -> Behavior -> Auto-merge criteria. Gitar evaluates them against the PR’s metadata, changed files, and diff size, separately from the auto-approve criteria. A PR can be approved and still not be armed.
Criteria cannot reference CI status. Your platform already holds the merge until its own checks pass, so a criterion like “tests are green” is treated as satisfied.

​
Use PR risk in criteria

Merge criteria can use the same risk assessment as code review and auto-approve, for example, “Merge only low-risk changes.” A clean review does not by itself establish low risk.

​
Per-Repository Criteria

A repository can add its own criteria by committing .gitar/config/merge.md:
.gitar/config/merge.md
Repository criteria are added to your organization’s, never replace them. A PR has to satisfy both. Gitar reads the file from your default branch, so a PR that adds or deletes it cannot change its own outcome.

​
Requiring the File

Turn on Require .gitar/config/merge.md to make auto-merge opt-in per repository. With it on, Gitar arms auto-merge only in repositories that have committed the file. Everywhere else the approval still lands and the merge is left to you. This is the setting to use when you want auto-merge available org-wide but each team deciding for itself.
If the file exists but Gitar cannot read it, auto-merge is held for that run. The approval still goes through, and the next push re-evaluates.

​
Overriding on a Single PR

Comment gitar auto-merge:on to enable auto-merge for that PR regardless of merge criteria, or gitar auto-merge:off to disable it. Gitar must still approve the PR, and platform merge requirements still apply.

​
What Happens If It Fails

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

​
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.
Auto-merge requires Auto-Approve to be enabled. Gitar only arms auto-merge on PRs it has approved.