---
title: "How do I merge pull requests from Claude Code and other coding agents safely?"
description: "What happens after the agent opens the pull request: make sure CI runs, keep a human approval, queue it, keep agents from merging around the queue, and tell the agent what to do when a check fails."
url: https://mergify.com/guides/merge-pull-requests-from-coding-agents
---

Guide

# How do I merge pull requests from Claude Code and other coding agents safely?

Keep your required checks and a human approval, then let a merge queue do the merging. The agent queues its own pull request, the queue tests it against the real next main, and your rules decide what lands. The agent never merges directly.

By [Julien Danjou](https://mergify.com/about), Co-founder & CEO of MergifyUpdated November 4, 2026

## In one paragraph

Generating the pull request is the part agents already do well. The risk sits in the steps after it, and each has a specific way to go wrong: CI that never starts because of the token the agent used, an approval from another bot, a push that drops the pull request out of the queue, a flaky test the agent tries to fix by rewriting working code. This guide walks those steps in order, with the config and the CLI calls to put in the agent's instructions.

## What happens after the agent opens the pull request?

Five things have to go right before the change is on main:

| Stage | What should happen | How it goes wrong |
| --- | --- | --- |
| CI starts | Your required checks run on the branch. | The runs never start, because of the token the agent used. |
| Review | A person approves the change. | Another agent's approval satisfies the rule. |
| Queueing | The agent asks for the queue. The pull request waits for its approval and checks. | The agent keeps pushing, and each push cancels the request. |
| Queue run | CI runs on the latest main plus the pull requests ahead of this one. | It fails, and the agent retries blindly or rewrites working code. |
| Merge | The queue merges the state it just tested. | Someone, or something, merges around the queue. |

## Will CI even run on the agent's pull request?

It depends on the token. A workflow that opens a pull request with the default `GITHUB_TOKEN` gets [runs in an approval-required state](https://docs.github.com/en/actions/concepts/security/github_token): nothing happens until someone with write access presses the button. GitHub's fix is a GitHub App token or a personal access token.

-   **Claude Code GitHub Actions:** if you pass `github_token: ${{ secrets.GITHUB_TOKEN }}` to `claude-code-action`, [Anthropic's docs](https://code.claude.com/docs/en/github-actions) say to remove it so the action authenticates as the Claude GitHub App, or to pass a custom app token.
-   **GitHub Copilot:** workflows [do not run automatically](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/review-copilot-prs) when Copilot pushes to a pull request. Someone clicks **Approve and run workflows** in the merge box.
-   **An agent on a laptop or in a sandbox:** it pushes with whatever credential you gave it. A personal token or an app token starts CI normally.

A required check that never starts is easy to miss, since the pull request just sits there looking pending. Check this first when an agent's pull requests stop moving.

## Who approves it?

A person, and you can write that down. A required approval on GitHub counts any reviewer with write access, which can include a bot account running a review agent. Turn on required review from code owners in the branch's ruleset and name a team of people as the owners:

```
# .github/CODEOWNERS
* @acme/platform
```

Only a member of that team can now give the approval that counts, and Mergify reads the ruleset, so the queue waits for it too. GitHub has a similar rule of its own for Copilot: [your approval of a pull request you asked Copilot to open does not count](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/review-copilot-prs) toward required reviews, so someone else has to approve it. [Testing AI-generated pull requests](https://mergify.com/guides/test-ai-generated-pull-requests) covers what the checks themselves should be.

## How does the pull request get into the queue?

The agent asks. It can comment `@mergifyio queue` on the pull request, or run `mergify queue add 4821` with the [Mergify CLI](https://docs.mergify.com/cli/usage). Either one can come before the review: the request stays pending until the pull request is approved and its required checks pass, so the agent can ask once and move on to its next task. `mergify queue add` on a pull request that is already queued exits 6 with `PULL_REQUEST_ALREADY_QUEUED`, which an agent can treat as done.

One rule for the agent: [stop pushing](https://docs.mergify.com/commands/queue). A push cancels a pending queue request, because the request vouched for the commits that were there when it was made. Once the pull request is in the queue, a push takes it out. Agents that keep polishing a branch after asking for a merge lose their place every time.

## How do I stop an agent from merging around the queue?

Instructions are a request, and a token with write access can still call `gh pr merge`. If the queue is meant to be the only path to main, enforce it on GitHub's side. [Exclusive mode](https://docs.mergify.com/merge-queue/deploy) uses a ruleset with Mergify on the bypass list, set up from **Merge Queue > Deployment** in the dashboard, and after that only Mergify can merge. People lose the green button too, which is what you want once the team has settled into the queue. Until then, hybrid mode lets queue merges and manual ones coexist.

## How do I keep agents from crowding out everyone else?

Give the queue more capacity. Forty refactors queued overnight should not leave a hotfix waiting at nine in the morning. [Batching](https://mergify.com/guides/cut-ci-costs-batching-bisection) lets several of them share one CI run, and it takes one setting:

```
queue_rules:
  - name: default
    batch_size: 5
```

In a monorepo, [scopes](https://mergify.com/learn/monorepo/merge-queue) also keep changes in different parts of the repository out of each other's way.

## What does the agent do when something fails?

It asks before it changes code. A person who sees a test fail remembers it has been doing that all week. An agent has no such memory, so it rewrites something, reruns, and either burns its run or lands a pointless change. Three CLI calls cover the loop:

```
# Ask to queue pull request 4821. It enters once it is approved and green.
mergify queue add 4821

# Where is it? If it left the queue: why, and which checks failed.
mergify queue show 4821

# Is this failing test flaky, or did the change break it?
mergify tests show 'tests/billing/test_invoice.py::test_rounding' --json
```

`mergify queue show` works after the pull request has left the queue too, and prints the reason (`CHECKS_FAILED`, for one) with the job log URL. `mergify tests show` takes the full test name or a glob, since a bare function name matches nothing. Its `--json` output gives each test a `health_status` of `healthy`, `flaky` or `broken` from [Test Engine](https://mergify.com/product/test-engine). Read that field, since the command exits 0 on a flaky test too. It answers from your default branch, so a test the pull request just added has no history to read yet. A batch failure is the queue's problem to solve: it splits the batch, finds the pull request responsible, and merges the rest, so an agent whose pull request is still queued has nothing to do.

## How does the agent learn all this?

Install the Mergify skills. They teach the agent everything above: queueing a pull request, reading why it left the queue, checking whether a failing test is flaky, plus stacked pull requests and the configuration. They live in the [mergify-cli repository](https://github.com/Mergifyio/mergify-cli).

```
# Claude Code
claude plugin install mergify

# Other agents
npx skills add Mergifyio/mergify-cli
```

If your agent does not load skills, or you want the rules written down in the repository, put this in `CLAUDE.md`, `AGENTS.md` or wherever it reads its instructions:

```
## Landing a pull request

- Open the pull request and wait for its checks. Never merge it yourself.
- When it is ready for review, ask for a review and run
  `mergify queue add <number>`. It enters the queue once it is approved and green.
- Do not push to the branch after that. A push cancels the request, or takes the
  pull request out of the queue. If a review asks for changes, push them and queue
  it again.
- If a test fails, run `mergify tests show '<full test name>' --json` before
  changing any code. If `health_status` is `flaky`, the failure is probably not yours: say
  so on the pull request and leave the code alone.
- If the pull request leaves the queue, run `mergify queue show <number>`. It
  prints the reason and the failing checks. Fix the cause, push, and queue it again.
```

## FAQ

### Does this replace Claude Code GitHub Actions?

No, the two sit one after the other. claude-code-action runs Claude Code inside a workflow and can turn an issue into a pull request. Mergify starts where that ends, with the pull request, and handles testing it against main and merging it.

### Does this work with Cursor, Codex and Copilot too?

Yes. The queue sees a GitHub pull request, whichever tool opened it. The differences are in how each agent authenticates, which decides whether your CI starts on its own, and in what you can put in its instructions.

### Can an agent merge without a human approval?

Only if your branch rules allow it. The queue applies the reviews your ruleset requires, so on a branch that requires an approval, an agent's pull request waits for one like any other.

### What credential does the agent need for the Mergify CLI?

An admin application key in MERGIFY\_TOKEN, or a user credential from mergify auth login. A ci application key is refused by mergify tests show.

### How does the agent find out the pull request merged?

mergify queue show reports it, for a pull request that is still queued and for one that has left: merged by the queue, dequeued with a reason, or never queued. With --json the same answer is machine-readable.

Full reference: [the queue command](https://docs.mergify.com/commands/queue), [deploying your merge queue](https://docs.mergify.com/merge-queue/deploy) and [the CLI](https://docs.mergify.com/cli).

Last updated: November 4, 2026

## Your agents open the pull requests. Let the queue land them.

Keep your checks and your reviewers, and test every change against the main it lands on. Free for up to 5 users.

[Get started](https://dashboard.mergify.com/)[See how Merge Queue works](https://mergify.com/product/merge-queue)