Configure automerge for GitHub Apps

Set up GitHub workflows to automatically merge Mintlify pull requests by enabling squash merging and granting the Mintlify GitHub App bypass on branch rules.

Configure your repository so that the Mintlify GitHub App can create and merge pull requests without review and status check requirements blocking it. This allows you to set up workflows that automatically merge changes to main.

Automerge requires two things on your repository:

1. Squash merging is enabled. Mintlify uses squash merge to land PRs.
2. The Mintlify GitHub App can bypass branch rules. Add the app to the bypass list for every ruleset or classic branch protection rule that requires reviews on your deploy branch.

The dashboard shows an automerge setup banner on your workflows page if either requirement is missing. Use the banner’s links to jump directly to the GitHub settings you need to update.

The Mintlify GitHub App must have bypass permissions on every ruleset and branch protection rule that targets your deploy branch, including rules defined at the organization level and the repository level. If any rule is missing the bypass entry, the workflow creates a PR, but does not merge it.

Prerequisites

• Repository admin access (and organization admin access if there are org-level rulesets)
• Mintlify GitHub App installed on the repository
• Squash merging enabled on the repository
• One or more rulesets or branch protection rules targeting the main branch (at the org or repo level)

Enable squash merging

1. On GitHub, go to your repository’s Settings -> General.
2. Under Pull Requests, select Allow squash merging.
3. Click Save.

If squash merging is disabled, automerge cannot complete a merge even when all branch rule bypasses are configured correctly.

Add the Mintlify GitHub App to your branch rules

Repeat these steps for every ruleset that applies to your deploy branch. Both organization-level and repository-level rulesets.

1. Navigate to rulesets

   • Repository rulesets: On GitHub, go to your repository’s Settings -> Rules -> Rulesets.
   • Organization rulesets: Go to your organization’s Settings -> Rules -> Rulesets.
2. Select the ruleset

   Click a ruleset that targets your deploy branch, which is usually main.

3. Add the Mintlify GitHub App to the bypass list

   1. Under Bypass list, click Add bypass.
   2. Search for and select the Mintlify GitHub App.
   3. Set the bypass mode to Always.
4. Save

   Click Save changes.

5. Repeat for remaining rulesets

   If you have additional rulesets at the org or repo level that target your deploy branch, repeat steps 2–4 for each one.

If your repository uses classic branch protection rules instead of (or in addition to) rulesets, open Settings -> Branches, edit the rule that protects your deploy branch, and add the Mintlify GitHub App to Allow specified actors to bypass required pull requests.

Verify the setup

1. For contributors: Open a PR targeting main. Confirm that it still requires approval and passing status checks before you can merge.
2. For workflows: Trigger a workflow with automerge enabled. Confirm that the workflow runs and successfully merges a PR.
3. In the dashboard: Open the Workflows page and confirm that the automerge setup banner is no longer displayed.