Configure automerge for GitHub Apps

Set up GitHub workflows to automatically merge Mintlify pull requests by adding the Mintlify bot to your repository’s ruleset bypass list.

Add the Mintlify GitHub App to a ruleset’s bypass list so that the app can create and merge pull requests without review and status check requirements blocking it. This allows you to configure workflows to automatically merge changes to main.

The Mintlify GitHub App must have bypass permissions on every ruleset that targets your deploy branch, including rulesets defined at the organization level and the repository level. If any ruleset 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 (Settings -> General -> Pull Requests -> Allow squash merging)
• One or more rulesets targeting the main branch (at the org or repo level)

Steps

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.

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.

Troubleshoot automerge

If your automerge setup is incomplete, the Workflows page in your dashboard shows a warning banner above the workflow list with a link to the GitHub settings you need to update. The banner appears for any of the following reasons:

• Squash merging is disabled: Enable Allow squash merging in your repository’s pull request settings so Mintlify can merge automerge workflow PRs.
• Branch rules need a Mintlify bypass: Add the Mintlify GitHub App to the bypass list on every ruleset targeting your deploy branch, following the steps above.
• A previous automerge run could not be accepted: Review the most recent failed run, fix the underlying GitHub configuration, then re-run the workflow.

Click Set up on GitHub in the banner to jump directly to the relevant settings page. You can dismiss the banner once you’ve resolved the issue.