# GitHub Branch Protection Guide: Preventing Direct Commits to Main

## Introduction

Branch protection rules are essential for maintaining code quality and preventing accidental or unauthorized changes to important branches like `main`. This guide will walk you through setting up branch protection rules in GitHub and ensuring they're properly enforced across your organization.

### Setting Up Branch Protection Rules

#### Basic Branch Protection

1. Navigate to your repository on GitHub
2. Click on "Settings" in the top navigation bar
3. In the left sidebar, click on "Branches"
4. Under "Branch protection rules," click "Add rule"
5. In the "Branch name pattern" field, enter `main` (or your default branch name)
6. Check the following options:
   * "Require a pull request before merging"
   * "Require approvals" (set the number of required reviewers, typically at least 1)
   * "Dismiss stale pull request approvals when new commits are pushed"
   * "Require status checks to pass before merging"
   * "Require branches to be up to date before merging"

<figure><img src="https://2337193041-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHET0AD04uHMgdeLAjptq%2Fuploads%2FZV0flOsfEdT4PuGMAMtt%2Fimage.png?alt=media&#x26;token=0ca58f17-40ed-458d-bd9b-f7b555d9de06" alt=""><figcaption></figcaption></figure>

Under "Rules applied to everyone including administrators", check "**Do not allow bypassing the above settings**"

<figure><img src="https://2337193041-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHET0AD04uHMgdeLAjptq%2Fuploads%2FEXcThDhxaSdTi5nr83MG%2Fimage.png?alt=media&#x26;token=b3067e1b-d3d4-4232-964b-e591bc602342" alt=""><figcaption></figcaption></figure>

#### Advanced Protection Settings

For stronger protection:

1. Enable "Include administrators" to apply rules to everyone
2. Check "Restrict who can push to matching branches" if you want only specific teams/people to merge PRs
3. Enable "Allow force pushes" only for specific people/teams if absolutely necessary

### Enforcing Organization-Wide Branch Protection

To ensure consistent protection across all repositories:

#### Using Organization Repository Rules

1. Navigate to your GitHub organization
2. Click on "Settings" in the top navigation menu
3. In the left sidebar, click on "Repository rules"
4. Click "New rule"
5. Name your rule (e.g., "Main Branch Protection")
6. Under "Branch protections", configure the same settings as above
7. Set the rule to apply to:
   * All repositories, or
   * Repositories matching specific criteria (e.g., visibility, topics)
8. Click "Create rule"

#### Using GitHub Enterprise Policies (For Enterprise Accounts)

If you have GitHub Enterprise:

1. Go to your enterprise account settings
2. Navigate to "Policies" > "Repository"
3. Under "Repository policies", scroll to "Branch protection rules"
4. Enable "Require branch protection rules" and configure the default settings
5. Save your changes

### Verifying Branch Protection

To ensure your protections are working correctly:

1. Try pushing directly to the main branch from a local repository

   ```bash
   git checkout maingit commit -m "Test commit"git push
   ```

   This should be rejected with an error message

<figure><img src="https://2337193041-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHET0AD04uHMgdeLAjptq%2Fuploads%2FTgp9kVpYGpFXSgxx2drB%2Fimage.png?alt=media&#x26;token=cec207a2-f36a-4a8a-a158-a9bcc72e81d6" alt=""><figcaption></figcaption></figure>

1. Create a new branch, commit changes, and open a pull request

   ```bash
   git checkout -b feature-branchgit commit -m "Test PR"
   git push -u origin feature-branch
   ```

   Then create a PR in the GitHub UI
2. Attempt to merge the PR without meeting requirements (this should be blocked)

{% hint style="warning" %}

#### Troubleshooting Common Issues

* **Settings not applying**: Verify "Include administrators" is checked
* **Bypassed protections**: Check that "Do not allow bypassing the above settings" is enabled
* **Repository-specific exceptions**: Review organization rules for conflicts
* **Branch deletion issues**: Enable "Restrict deletions" in branch protection settings
  {% endhint %}

### Best Practices

* Protect all production branches (`main`, `production`, etc.)
* Require at least one review for all PRs
* Configure required status checks for CI/CD pipelines
* Consider requiring signed commits for additional security
* Regularly audit branch protection settings across repositories
* Document your branch protection strategy for team reference

By implementing these protections, you'll help ensure code quality and prevent accidental deployments to critical branches.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.paradime.io/app-help/concepts/working-with-git/github-branch-protection-guide-preventing-direct-commits-to-main.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.