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.

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

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.

​
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 this, Gitar will approve the PR but auto-merge will not be armed.
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.

​
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

​
Auto-Merge Criteria

By default every auto-approved PR is armed for merge. Criteria narrow that down. Write them in plain language in Settings → 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.

​
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 on a PR to arm it regardless of criteria, or gitar auto-merge:off to keep it from being armed. An explicit instruction on the PR always wins.

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

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