Alex: Welcome back. Today we're talking about branch protection and repository rulesets, which are the reason a pull request can look finished and still not be mergeable.

Jamie: That is such a familiar moment. You've written the change, opened the pull request, maybe even fixed feedback, and then the Merge button is disabled. It can feel like GitHub is just saying no.

Alex: Usually it is saying not yet, and it is giving you clues. A branch protection rule is a set of requirements that must be satisfied before changes can enter an important branch, usually main.

Jamie: So this is about protecting main from accidental changes, not about making contributors jump through hoops for fun.

Alex: Exactly. Protection can require review, passing tests, signed commits, an up-to-date branch, or a pull request instead of a direct push. Contributors mostly experience those rules in the merge box at the bottom of the pull request, while maintainers and facilitators configure the rules behind the scenes.

Jamie: Let's make the classic version concrete. What are the rules people run into most often?

Alex: The most common one is required reviews. A maintainer can say that a pull request needs one approval, or two approvals, or approval from a code owner before it can be merged.

Jamie: And if someone already approved, but then I push another commit, does that approval still count?

Alex: Sometimes yes, sometimes no. If the repository dismisses stale reviews, a new push withdraws the old approval, because the reviewer approved an earlier version of the work. If a reviewer requested changes, you respond, push the fix, and re-request review.

Jamie: Status checks are the other big one, right?

Alex: Right. A status check is an automated report attached to your commit. It might come from GitHub Actions, or from a third-party continuous integration service, which is software that builds, tests, or scans the project after you push.

Jamie: What names might a learner hear or see in the checks list?

Alex: Common examples are ci / build, ci / test, lint, accessibility-check, CodeQL, and deploy previews from services like Netlify. If a check is required, pending or failing means the merge stays blocked until that check succeeds.

Jamie: Then there is the message about the branch being out of date with the base branch.

Alex: That means main moved after you created your branch, and the repository requires your pull request branch to include the latest main before merging. GitHub may offer an Update branch button, or you may update locally with fetch and rebase if the project allows that and you're comfortable doing it.

Jamie: What about signed commits? That one can sound a little mysterious.

Alex: A signed commit has a verified cryptographic signature, often using GPG or SSH signing. If a repository requires signed commits, every commit in the pull request needs that Verified status, or the pull request cannot be merged.

Jamie: And there are a few rules that shape the history itself.

Alex: Yes. Requiring a linear history means the project does not allow merge commits into that branch, so maintainers usually squash merge or rebase merge instead. A push restriction says only listed people, teams, or apps can push to the branch. A locked branch is stricter: it is effectively read-only, often during a release freeze or for an archived project.

Jamie: Classic branch protection still exists, but GitHub also has repository rulesets. What changed?

Alex: Repository rulesets are the newer, more flexible approach GitHub introduced in late 2023. They can apply rules to patterns of branches or tags, and in organizations they can be managed across multiple repositories from one place.

Jamie: So instead of one rule for one branch in one repo, a maintainer can say, apply this to main, release branches, or version tags.

Alex: Exactly. Classic branch protection is usually single repository, single branch. Rulesets can target patterns like main, release/*, or v*, include bypass lists, show violation insights, and run in Active, Evaluate, or Disabled mode.

Jamie: Evaluate mode sounds useful. Is that like a trial run?

Alex: Yes. It logs what would have been blocked without actually blocking it. That gives maintainers a safer way to test a policy before enforcing it.

Jamie: Where would someone look for rulesets?

Alex: If you have access, you may find them under the repository's Insights tab, then Rulesets, or under Settings, Rules, Rulesets for admins. Contributors often do not have that access, and that's okay, because the pull request merge box still explains what is blocking the merge.

Jamie: If I were configuring one, what would the shape of that workflow be?

Alex: An admin opens repository settings, goes to Rules, creates a new ruleset, gives it a name, and chooses whether it targets branches or tags. Then they add patterns, such as main for the default branch, release/* for release branches, or v* for version tags. After that they choose rules, set enforcement to Active or Evaluate, review any bypass entries, and save.

Jamie: Tag patterns are important because releases are often tied to tags, aren't they?

Alex: They are. A project may protect tags so people cannot delete a release tag or create version tags outside the release process. That is especially helpful when packages, documentation sites, or deployments trust those tags.

Jamie: Let's go back to the contributor experience. The pull request is open, the merge button is unavailable, and the page says reviews are required. What now?

Alex: First, check how many approvals are required and whether a code owner or maintainer needs to review. Use the Reviewers area in the right sidebar to request review if that is appropriate for the project. If changes were requested, respond, push the update, and ask for another look.

Jamie: What if the message says checks have not completed, or checks were not successful?

Alex: Go to the merge box and expand Show all checks if the list is collapsed. Find the failing check, open Details, and read the log for the error. Then fix the underlying problem in your branch and push again, which usually reruns the checks automatically.

Jamie: And if it is just sitting there forever?

Alex: Most workshop and small project checks finish in a few minutes. If a required check stays in progress for a long time, say more than 30 minutes, it may be a runner or service problem, so contact the maintainer. If the same check passes on main but fails on your pull request, assume your change triggered something and read the log carefully.

Jamie: The out-of-date message is less scary once you know what it means.

Alex: Yes. If GitHub shows Update branch, that button merges the latest main into your pull request branch. The local alternative is usually git fetch upstream, then rebase onto upstream/main, followed by a push, but only use that path when you understand the project's expectations around rebasing.

Jamie: And for verified signatures?

Alex: You need to set up commit signing, usually with GPG or SSH signing, then replace the unsigned commits with signed ones. That may mean recommitting, cherry-picking, or asking a maintainer which recovery path they prefer.

Jamie: Sometimes the page just says merging is blocked, which is not very soothing.

Alex: When that happens, read the status lines directly above the merge button. The cause may be missing review, failed checks, an out-of-date branch, required signatures, a locked branch, or a rule that restricts who can push or merge. The closest status text is usually more useful than the button label itself.

Jamie: The merge box matters a lot here. How should a screen reader user get to the part of the page that explains the block?

Alex: Open the pull request's Conversation tab, then move to the bottom of the page. Pressing End is often the fastest way to land near the merge area, and then heading navigation can help you find the merge heading. Listen for status lines such as 1 review required, checks pending, or branch out of date before trying the button.

Jamie: Can we be a little more specific for NVDA and JAWS users?

Alex: With NVDA, browse mode heading navigation is often a good path: press H until you reach the merge area, then use the arrow keys to read line by line. With JAWS, the virtual cursor works similarly, and the headings list can also help if the page is long. Once you find a Details link for a check, activate it to open the log.

Jamie: Low vision users get some visual cues too, but they are easy to miss.

Alex: The merge area uses green, yellow, and red indicators, but the text next to the icons is what you should trust. Zooming to 150 percent or more can make the checkmarks, X icons, and secondary Update branch button easier to find. Sighted users will also see a vertical checklist above the merge button, and Show all checks expands the full list when GitHub only shows a summary.

Jamie: Those check details pages can be noisy.

Alex: They can. GitHub Actions opens a run page with jobs, steps, and log output, while third-party checks may open an external dashboard. Start with the failed job name, then the first error message, because later errors can be side effects of the first failure.

Jamie: Let's define status checks a bit more, because they show up everywhere in protected branches.

Alex: A status check is a pass, fail, or pending report for a specific commit. In GitHub Actions, those reports usually come from workflow files in .github/workflows, such as .github/workflows/ci.yml. A workflow can run when someone opens a pull request, pushes to a branch, or updates the pull request.

Jamie: So a project might run tests every time I push to my pull request branch.

Alex: Exactly. The check may be queued, in progress, successful, failed, cancelled, or skipped. For a required check, the important result is successful; anything else may block the merge depending on how the rule is configured.

Jamie: And not every check comes from GitHub Actions.

Alex: Right. Services like Netlify, Vercel, CircleCI, security scanners, accessibility scanners, and code quality tools can all post checks back to GitHub. To the merge box, they all become signals about whether the current commit is ready.

Jamie: Who actually gets to configure all of this?

Alex: Repository admins and maintainers with the right permissions can configure branch protection in a repository. Organization owners can create organization-level rulesets, depending on the GitHub plan and organization settings. Contributors usually cannot change the rules, but they can still read the merge box and ask informed questions.

Jamie: You mentioned bypass lists earlier. Are those just exceptions?

Alex: Yes, but they should be deliberate exceptions. A ruleset can allow specific users, teams, roles, or apps to bypass selected rules, such as a release bot that needs to create a protected tag. Good projects keep bypass lists small and review them because bypassing a rule is a powerful action.

Jamie: How do these choices look in real project configurations?

Alex: For a small team, a practical setup might protect main, require pull requests, require one approval, and require the basic test workflow to pass. For an open source project, maintainers may add code owner review, dismiss stale reviews, restrict direct pushes, and require security or accessibility checks. In an enterprise, rulesets may be managed at the organization level with required scans, linear history, release tag protection, and Evaluate mode before a new rule becomes active.

Jamie: And in the workshop environment, learners are not usually trying to become repository admins on day one.

Alex: Right. The Learning Room repository is provisioned per learner, and it is where Day 1 contributions happen: issue, branch, commit, pull request, and merge. Facilitators can keep protections light for practice, or intentionally demonstrate a blocked merge so learners can hear and inspect the clues.

Jamie: If someone wants the most current reference, where should they go?

Alex: Use GitHub's documentation on protected branches, repository rulesets, Actions status checks, and commit signing. GitHub changes screens over time, so trust the current docs and the live messages in the pull request. If you can explain what rule is blocking you and what evidence would satisfy it, you're in good shape.

Jamie: I like that framing. A blocked merge is not a dead end. It is a checklist from the repository.

Alex: Exactly. Read the merge box, open the details when needed, make the next change, and verify that the status changed. That is how protected branches turn from a mystery into a normal part of collaboration.