> ## Documentation Index
> Fetch the complete documentation index at: https://empirical.run/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Repository settings

> GitHub settings Empirical needs to open and merge pull requests in your test repository

If your [test repository](https://empirical.run/docs/platform/repository) lives in your GitHub organization, Empirical's agents
open pull requests there through the `empiricalrun` GitHub App and merge them once the changes are
ready. A few repository settings decide whether those merges go through.

Open **Settings → Repository** in the dashboard. The **GitHub settings** card checks the repository
and links to the GitHub page for anything that needs a change.

## Checks

| Check | Level | Why |
| - | - | - |
| Empirical's GitHub App has access | Required | The app must be able to read and write the repository. Grant it from your organization's **Settings → GitHub Apps**, under **Configure** for empiricalrun. |
| Merge commits are on | Required | Empirical merges pull requests with merge commits. |
| Default branch matches | Required | GitHub's default branch must be the same branch Empirical uses for test runs and merges. |
| Squash merging is off | Recommended | Squashing rewrites commits, so Empirical cannot tell the branch was merged and reusing it causes conflicts. |
| Rebase merging is off | Recommended | Same as squash merging. |

Merge settings live in GitHub under **Settings → General → Pull Requests**.

## Branch protection

The card also lists the rulesets that apply to the default branch, including organization rulesets,
and whether the Empirical GitHub App can bypass them. A ruleset that requires approvals or status
checks holds back Empirical's pull requests unless the app is on its bypass list.

Rules that only restrict pushes, such as blocking force pushes or deletion, do not affect Empirical
and are listed separately.

## Let Empirical merge pull requests

To let Empirical merge its own pull requests while direct pushes to the default branch stay blocked,
add the `empiricalrun` app as a bypass actor. Do this everywhere the default branch is protected:
rulesets and classic branch protection both apply, and the stricter result wins.

### Rulesets

1. Open the ruleset in GitHub. The **Add bypass** button in the dashboard opens it directly. Organization
   rulesets are in your organization's settings, repository rulesets under the repository's
   **Settings → Rules → Rulesets**.
2. Under **Bypass list**, click **Add bypass** and search for `empiricalrun` (listed under apps).
3. Set its mode to **For pull requests only**, then save the ruleset.

To limit the bypass to the test repository, keep the organization ruleset as is for other repositories:
exclude the test repository from it and add a repository ruleset with the bypass there.

### Classic branch protection

1. In the test repository, open **Settings → Branches** and edit the rule for the default branch.
2. Under **Require a pull request before merging**, check **Allow specified actors to bypass required
   pull requests**.
3. Search for `empiricalrun`, add it, and save the rule.

![Classic branch protection with empiricalrun allowed to bypass required pull requests](https://mintcdn.com/empirical/AuDI30UWFwIY4X62/images/repository-settings/classic-protection-bypass.png?fit=max\&auto=format\&n=AuDI30UWFwIY4X62\&q=85\&s=ad48cc2e861047838321631a38536d21)

The GitHub App does not have permission to read classic branch protection, so the dashboard cannot show
these rules. If a merge is still blocked after the ruleset bypass shows as allowed, check classic
protection on the default branch.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.