> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/code-repository/3.0/use-harness-code/pull-requests/auto-merge-pr.md).

# Auto-Merge Pull Requests

Automatically merge pull requests when all merge requirements are met in Harness Code.

Auto-merge lets you queue a pull request to merge automatically once all [merge requirements](/code-repository/3.0/use-harness-code/pull-requests/merge-pr.md#merge-requirements) are satisfied. This is useful when a PR is ready for integration but is waiting on status checks, required approvals, or other branch rules to pass.

When auto-merge is enabled on a PR, Harness Code monitors its requirements continuously. As soon as every required check passes and all approvals are in place, the PR merges using the strategy you selected, with no manual action needed.

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

* **Auto-merge enabled on the repository:** A repository administrator must [turn on the **Allow auto-merge** setting](#enable-auto-merge-for-a-repository) in repository settings before contributors can use auto-merge on individual PRs.
* **Open, non-draft pull request:** Auto-merge is only available on PRs that are open and not in draft state.
* **Pending merge requirements:** The **Enable auto-merge** button appears only when the PR has unmet requirements (status checks running, approvals pending, or branch rule violations) that currently block a direct merge. If the PR is already mergeable, you can [merge it directly](/code-repository/3.0/use-harness-code/pull-requests/merge-pr.md).

### Enable auto-merge for a repository <a href="#enable-auto-merge-for-a-repository" id="enable-auto-merge-for-a-repository"></a>

Before contributors can use auto-merge on individual PRs, a repository administrator must enable it at the repository level.

1. In Harness Code, go to the repository where you want to enable auto-merge.
2. Go to **Settings**, and then select the **General** tab.
3. Under **Features**, select the **Allow auto-merge** checkbox.

The setting takes effect immediately. Contributors can now enable auto-merge on individual PRs in this repository.

{% hint style="info" %}
Disabling **Allow auto-merge** in repository settings does not cancel auto-merge on pull requests where it is already active. Those PRs continue to merge automatically when their requirements are met. The setting only prevents contributors from enabling auto-merge on new PRs going forward. To stop an in-progress auto-merge, you must [disable it directly on the PR](#disable-auto-merge-on-a-pull-request).
{% endhint %}

### Enable auto-merge on a pull request <a href="#enable-auto-merge-on-a-pull-request" id="enable-auto-merge-on-a-pull-request"></a>

Once auto-merge is enabled at the repository level, contributors can turn it on for individual PRs that have pending merge requirements.

1. In Harness Code, go to **Pull Requests**, and select the PR.
2. In the merge panel at the bottom of the **Conversation** tab, select a merge strategy from the **Enable auto-merge** dropdown:

   * **Squash and merge:** Combines all commits into a single commit on the base branch.
   * **Merge pull request:** Adds all commits to the base branch via a merge commit.
   * **Rebase and merge:** Rebases all commits onto the base branch.
   * **Fast-forward merge:** Moves the base branch pointer forward without creating a merge commit.

   Available strategies depend on the repository's [branch rules](/code-repository/3.0/use-harness-code/manage-repositories/rules.md) and the branch history.
3. For **Squash and merge** or **Merge pull request**, you can optionally customize the commit message and description.
4. Select **Confirm auto-merge**.

The merge panel updates to show that auto-merge is active and displays the selected merge strategy. The PR merges automatically when all requirements are met.

{% hint style="info" %}
If you choose **Squash and merge**, the commit description is pre-populated with a summary of the PR's commits. You can edit this before confirming.
{% endhint %}

### Disable auto-merge on a pull request <a href="#disable-auto-merge-on-a-pull-request" id="disable-auto-merge-on-a-pull-request"></a>

If you change your mind or need to adjust the merge strategy, you can disable auto-merge at any time before the PR is merged.

1. Go to the PR's **Conversation** tab.
2. Select **Disable auto-merge**.

The PR returns to its normal state and will not merge automatically.

### Bypass rules with auto-merge active <a href="#bypass-rules-with-auto-merge-active" id="bypass-rules-with-auto-merge-active"></a>

If you have bypass permissions and auto-merge is active on a PR, you can choose to bypass branch rules and merge immediately instead of waiting for all requirements.

Select the **Bypass and merge** checkbox in the merge panel. This overrides the auto-merge queue and lets you merge the PR directly, following the standard [merge flow](/code-repository/3.0/use-harness-code/pull-requests/merge-pr.md).

### Auto-merge failure <a href="#auto-merge-failure" id="auto-merge-failure"></a>

Auto-merge can be automatically disabled if the selected merge strategy is no longer supported by the repository's branch rules. For example, if an administrator removes **Squash and merge** from the allowed strategies after you enabled auto-merge with that method, auto-merge is disabled and a timeline entry appears on the PR:

> disabled auto-merge — squash is no longer a supported merge method

To resolve this, [enable auto-merge again](#enable-auto-merge-on-a-pull-request) with a strategy that is currently allowed.

### Known limitation: rule, user group, and role changes <a href="#known-limitation-rule-user-group-and-role-changes" id="known-limitation-rule-user-group-and-role-changes"></a>

Auto-merge is event driven. The auto-merge subsystem re-evaluates a PR only when an event occurs on that PR, such as a status check reporting a result, an approval being submitted, or a new commit being pushed.

The following changes do not emit a PR event, so they do not re-evaluate pull requests that already have auto-merge active:

* **Rule edits:** Any change to an existing rule, including adding or removing a required status check.
* **New rules:** A rule created after auto-merge was enabled on the PR.
* **User group membership changes:** Users added to or removed from a user group.
* **Role assignment changes:** Roles granted to or revoked from a user or user group.

Rule level does not matter. Rules at the account, organization, project, and repository levels are all treated the same way.

If one of these changes is the only thing that makes a PR mergeable, the PR does not merge automatically. For example, an account-level rule requires three approvals. A PR collects two approvals, so auto-merge stays queued. An administrator then edits the rule to require two approvals. The PR now satisfies the requirement, but auto-merge does not merge it.

{% hint style="warning" %}
The PR displays the new, updated merge requirements, so the PR looks ready to merge even though auto-merge has not re-evaluated it. Use the merge panel state as a view of the current requirements, not as confirmation that auto-merge has processed them.
{% endhint %}

To merge a PR in this state, do any of the following:

* **Push a commit or submit an approval:** Each of these emits an event that the auto-merge subsystem picks up, which triggers a new merge attempt.
* **Re-enable auto-merge:** [Disable auto-merge](#disable-auto-merge-on-a-pull-request), and then [enable auto-merge](#enable-auto-merge-on-a-pull-request) again. Enabling auto-merge attempts a direct merge first, so the PR merges immediately if it now satisfies every requirement.
* **Merge the PR yourself:** Complete the [manual merge flow](/code-repository/3.0/use-harness-code/pull-requests/merge-pr.md) with any strategy the branch rules allow.

This behavior is intentional. Harness Code supports rules at four levels, and a change at a higher level propagates to every level below it, so a single account-level rule edit would require inspecting every open pull request in every repository across the account. User groups and role assignments are also stored outside Harness Code. Reprocessing every auto-merge pull request on every such change is too expensive to justify, and a change to this behavior is not on the roadmap.

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

<details>

<summary>Enable auto-merge button does not appear on a Harness Code pull request</summary>

Verify that Allow auto-merge is enabled in the repository's Settings > General > Features, the PR is open (not draft), and the PR has pending merge requirements that block a direct merge.

</details>

<details>

<summary>Auto-merge was disabled automatically on a Harness Code pull request</summary>

The selected merge strategy may no longer be allowed by the repository's branch rules. Re-enable auto-merge with a currently supported strategy.

</details>

<details>

<summary>Pull request shows all merge requirements as met, but auto-merge did not merge it</summary>

Auto-merge only re-evaluates a PR when an event occurs on that PR. Rule edits, new rules, user group membership changes, and role assignment changes are not PR events, so the PR displays the updated requirements without auto-merge acting on them. Push a commit or submit an approval, or disable and re-enable auto-merge, to trigger a new merge attempt. The [known limitation on rule, user group, and role changes](#known-limitation-rule-user-group-and-role-changes) explains why this happens.

</details>

### Next steps <a href="#next-steps" id="next-steps"></a>

You've learned how to configure and use auto-merge for pull requests in Harness Code. Auto-merge is especially useful in CI-heavy workflows where PRs frequently wait on pipeline checks before they can be integrated.

* [Merge PRs](/code-repository/3.0/use-harness-code/pull-requests/merge-pr.md): Learn about merge strategies and requirements.
* [Branch rules](/code-repository/3.0/use-harness-code/manage-repositories/rules.md): Configure required checks, approvals, and allowed merge strategies.
* [Review PRs](/code-repository/3.0/use-harness-code/pull-requests/review-pr.md): Understand the review and approval process.

{% @harness-feedback/feedback %}