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

> Automatically approve pull requests after a clean code review

## Overview

Auto-approve lets Gitar submit an approving review on your behalf after a clean code review. You define criteria in natural language, and if they are met, Gitar approves the PR without any manual action required.

<CardGroup cols={3}>
  <Card title="Criteria-Driven" icon="sliders">
    Define approval conditions in natural language — or use the default behavior with no criteria at all
  </Card>

  <Card title="Post-Review Only" icon="shield-check">
    Only runs after a clean code review with no blocking findings
  </Card>

  <Card title="Per-Repo Control" icon="code-branch">
    Extend org criteria per repository with a config file
  </Card>
</CardGroup>

## How It Works

<Steps>
  <Step title="Code review completes">
    Gitar reviews the PR or MR as usual. If there are blocking findings (severity: Important or above), auto-approve is skipped.
  </Step>

  <Step title="Criteria are checked">
    Gitar evaluates your configured criteria against the PR metadata, changed files, and review results. If no criteria are configured, Gitar will approve the PR if there are no blocking issues found.
  </Step>

  <Step title="Approval is submitted">
    Gitar submits an approving review on GitHub or GitLab. The dashboard comment shows the approval and the rationale.
  </Step>
</Steps>

## Enabling Auto-Approve

Auto-approve is configured in your organization settings:

1. Navigate to **Settings** in the Gitar dashboard
2. Open the **Behavior** section
3. Enable the **Auto-approve PRs/MRs based on code review** toggle
4. Optionally, enter custom approval criteria in the text area that appears

Criteria are written in natural language. Examples:

* "Only approve if the changes are limited to documentation or test files"
* "Approve changes to the `docs/` directory or files ending in `.md`"
* "Skip approval if the PR modifies authentication or payment logic"

<Note>
  Auto-approval criteria are evaluated against the PR metadata, changed files, and code review
  results — not CI pipeline status. Conditions like "tests pass" or "linting is green" are not verified by Gitar and should instead be enforced via your platform's branch protection or merge
  checks.
</Note>

### Default behavior (no criteria)

When the auto-approve toggle is enabled but no criteria are configured — neither in the dashboard nor in a repository's `.gitar/config/approve.md` — Gitar will approve the PR if there are no blocking issues found.

<Warning>
  If you previously had auto-approve enabled without criteria, your PRs were **not** being
  auto-approved. This default behavior was added in May 2026. Review your auto-approve settings if
  automatic approval is not desired.
</Warning>

## After Approval

When auto-approve fires, you can optionally chain additional actions from the same settings section.

### `gitar-approved` label

Enable the **Apply gitar-approved label** toggle to have Gitar add a `gitar-approved` label to approved PRs. The label is created automatically in your repository if it doesn't exist. This makes approved changes easy to filter in your platform's PR list.

### Auto-merge

Enable the **Auto-merge PRs/MRs after auto-approve** toggle to arm your platform's native auto-merge immediately after approval. On GitHub, you can also choose the merge method (squash, merge commit, or rebase). On GitLab, the project's default merge method is used.

See [Auto-Merge](/features/code-review/auto-merge) for prerequisites and details.

## Per-Repo Criteria

You can define criteria at the repository level by placing a Markdown file at `.gitar/config/approve.md`. This works independently or alongside org-level criteria:

* **Org criteria only** — applies to all repositories in the organization.
* **Repo criteria only** — applies to that repository even if no org criteria are set.
* **Both** — Gitar combines them and the PR must satisfy all criteria.

See [Repository Configuration](/configuration/repository-config) for more on the `.gitar` directory and how repo-level config files work.

```bash theme={null}
mkdir -p .gitar/config
echo "Only approve if no database migrations are included." > .gitar/config/approve.md
```

### Combination Logic

| Org criteria | Repo file | What happens                                                |
| ------------ | --------- | ----------------------------------------------------------- |
| Set          | Present   | Both are combined — PR must satisfy all criteria            |
| Set          | Absent    | Org criteria only                                           |
| Empty        | Present   | Repo file criteria only                                     |
| Empty        | Absent    | Default — approve when all code review issues are addressed |

## Platform Behavior

<AccordionGroup>
  <Accordion title="GitHub">
    Gitar submits an approving review on the PR. If your branch protection rules require an approving review, this satisfies that requirement.

    The review body reads: *"Gitar has auto-approved this PR"* with a link to your auto-approve settings.

    If auto-merge is also enabled, the review body mentions that auto-merge has been armed.
  </Accordion>

  <Accordion title="GitLab">
    Gitar approves the MR via the API. If your approval rules list Gitar as an eligible approver, this counts toward the required approval count.

    If auto-merge is also enabled, Gitar calls the GitLab API to arm auto-merge after approval.
  </Accordion>
</AccordionGroup>

## Revocation

If a new push introduces blocking findings, Gitar revokes its previous approval:

* On GitHub, Gitar dismisses its approving review.
* On GitLab, Gitar calls the unapprove API.
* If auto-merge was armed, it is also disabled.

The `gitar-approved` label is not removed automatically — you can configure a rule to handle this if needed.

<Note>
  Auto-approve only ever submits approvals and never requests changes. If anything goes wrong during
  evaluation, the step is skipped and the PR is unaffected (fail-open).
</Note>