Branch protection & required checks

You’ve got a working CI pipeline that runs tests and builds artifacts — but nothing stops anyone from pushing straight to main with a broken test. Without branch protection and required checks, your main branch is a wild west, and a single bad merge can ship production-breaking code. This lesson shows you how to lock down main like a professional team, enforce your CI gates, and turn your pipeline into a real safety net.

The problem this lesson solves

If your team has grown beyond a solo project, you’ve probably seen it happen: a developer pushes directly to main, skips the tests, and the whole deployment breaks. Maybe someone force-pushes over a reviewed PR, or a stale branch merges code that was never checked. The root cause isn’t lack of discipline — it’s the absence of automated guardrails. Branch protection rules are GitHub’s way of enforcing process: who can push, what checks must pass, and what happens when code doesn’t meet the bar.

Without required checks, your CI pipeline is a suggestion, not a gate. Adding branch protection and required checks turns your main branch from a free-for-all into a controlled environment where only verified code gets in. This lesson is the first real step toward professional, blame-free CI/CD — and it directly sets you up for the next lesson on merge strategies and pull request automation.

Core concept / mental model

Think of branch protection as the security guard at the entrance to a building called main. The guard has a list of rules: only authorized people can enter, and they must show a valid ID — in this case, a passing CI check. Without the guard, anyone can walk in. With it, only code that passes your checks and comes from a reviewed PR can merge.

Key terms to know:

• Branch protection rule — a set of conditions applied to a branch (like main) that restrict direct pushes and enforce review and check requirements.
• Required checks — CI status checks (e.g., GitHub Actions jobs) that must succeed before a merge is allowed.
• Required reviews — minimum number of approving reviews before merge.
• Merge queue — a queue that runs checks on the merged result before merging.

Here’s the mental flow: 1. A developer creates a branch. 2. They push code and open a PR. 3. CI runs checks on the PR. 4. If required checks pass and required reviews approve, the PR can merge. 5. If either fails, the merge is blocked.

How it works step by step

GitHub applies branch protection rules when a merge is attempted. Here’s the logical sequence:

1. Define the protected branch — usually main (or master).
2. Set required checks — list the status checks that must pass. Every commit pushed to the branch triggers these checks.
3. Set required reviews — choose how many approving reviews the PR needs.
4. Additional protections — prevent force pushes, allow only specific users or apps to push, or require a merge queue.
5. Merge is blocked unless all conditions are met.

Cause → effect: If a check fails, GitHub shows the PR as “checks failed” and blocks the merge button. If a reviewer hasn’t approved, the button stays gray. Only when every condition is green does the merge become possible.

Hands-on walkthrough

Let’s add branch protection to a GitHub repository and require our CI check. We’ll assume you have a GitHub repo with a workflow that runs tests (e.g., ci.yml).

Step 1: Identify your check name

Open your repo, click Actions, and run the workflow once on a branch. Note the check name — usually the job name, e.g., test or build-and-test.

Step 2: Add branch protection via UI

1. Go to Settings → Branches.
2. Under Branch protection rules, click Add rule.
3. In Branch name pattern, type main.
4. Check Require status checks to pass before merging.
5. In the search box, type the name of your check (e.g., test) and select it.
6. Check Require branches to be up to date before merging (recommended).
7. Also check Require a pull request before merging and set required approvals to 1.
8. Save.

Now any direct push to main is rejected, and a PR must pass the test check plus get an approval.

Step 3: Protect via CLI (using GitHub CLI)

If you prefer automation, use the gh CLI:

gh api \
  -X PUT /repos/{owner}/{repo}/branches/main/protection \
  -H "Accept: application/vnd.github+json" \
  -F required_status_checks[strict]=true \
  -F required_status_checks[checks][][context]=test \
  -F enforce_admins=true \
  -F required_pull_request_reviews[required_approving_review_count]=1 \
  -F required_linear_history=true

Replace {owner} and {repo} with your values. Note: the -F syntax sends JSON; you might need to adjust quoting for your shell.

Step 4: Test the protection

1. Create a new branch, change a file, and try to push directly to main:

git push origin main

Expected output:

remote: error: GH006: Protected branch update failed for refs/heads/main.
remote: error: Cannot force-push to this protected branch
To github.com:owner/repo.git
 ! [remote rejected] main -> main (protected branch hook declined)

1. Open a PR from your branch. Add a commit that fails the test, and observe the merge button is blocked. Then fix the test, push again, and once checks pass and you approve, merge the PR.

Step 5: Automate the rule via IaC (Terraform)

For larger teams, manage branch protection as code. A minimal Terraform example:

resource "github_branch_protection" "main" {
  repository_id = "my-repo"
  pattern       = "main"
  required_status_checks {
    strict = true
    contexts = ["test"]
  }
  required_pull_request_reviews {
    required_approving_review_count = 1
  }
}

Apply with terraform apply and the rule is reproducible everywhere.

Compare options / when to choose what

There are several ways to enforce branch protection. Here’s a comparison:

When to choose what: - Use the UI for a quick fix in one repo. - Use the API/CLI if you need to automate the same rule across many repos. - Use Terraform if your org treats infrastructure as code and needs auditability. - Use Merge Queue if you often have stale branches and want to test the merged result before merging.

Troubleshooting & edge cases

Symptom: Check not showing in the list of required checks - Cause: The workflow hasn’t run on the branch yet, or the check name is wrong. - Fix: Run the workflow once by pushing a commit to the branch or opening a PR. Confirm the exact job name in the workflow YAML.

Symptom: Direct push still works after enabling protection - Cause: The branch name pattern doesn’t match main, or the rule is overridden by a higher-priority rule. - Fix: Check that your pattern is exactly main. If you have wildcard rules, remember GitHub uses the most specific rule — ensure no conflicting rules exist.

Symptom: PR merge button says “Base branch is out of date” - Cause: You enabled “Require branches to be up to date before merging”. - Fix: Merge or rebase the target branch into your PR branch, or use a merge queue to handle it automatically.

Symptom: Force-push rejected even though you’re the owner - This is expected — protection blocks force-pushes, including for admins (if enforce_admins is on). - Fix: If you truly need to force-push (e.g., rewriting history on a feature branch), ensure protection applies only to main, not feature branches.

Symptom: Required reviews block your own PR - This is normal. You can’t approve your own PR. Ask a teammate to review, or temporarily lower the required approvals number while iterating (but turn it back up).

What you learned & what's next

You now understand why branch protection is essential, how required checks work, and how to add them using the UI, CLI, and infrastructure-as-code. You can protect main, enforce CI gates, and prevent bad code from merging. This is a huge step toward professional CI/CD.

Next lesson: Merge strategies and pull request automation — you’ll learn how to configure merge queues, auto-merge, and efficient branching strategies that complement your protection rules.