15.8 Checks that block
- Approved by
- Panaversity ·
In everyday life. A smoke detector beeps. A circuit breaker cuts the power. Both notice a problem, but only one stops anything. Each is right for its job. The mistake is to believe the beeper is a breaker.
What you will learn. How to tell a check that only reports from a check that stops a merge, and who decides which one it is.
Why it matters. A gate is a check that can really stop a merge. A team that mistakes a report for a gate has no gate.
What is a check on a pull request?
A command that a machine runs on the change, with a pass or a fail shown on the pull request. The commands are listed in a file in the repository, the checks file. GitHub calls it a workflow. Here is a small part of Brightline's:
jobs:
checks:
steps:
- run: npm run typecheck
- run: npm testjobs:starts the list of jobs. This part shows one.checks:is the name of that job. A job shows on the pull request as one check, with one pass or fail.- Each
- run:line is a step, one command. The first runs the type check, and the second runs the tests. You met both in Chapter 13.
Nobody types these commands. GitHub reads the file, and runs the jobs on its own machines each time a pull request to main opens or changes.
A check that only runs is the smoke detector. It reports, and nothing more.
What are Brightline's checks?
Three jobs:
| Job | What it fails on |
|---|---|
checks | A type error, a failing test, or a style problem |
tests-unchanged | A change that removes or edits a line in an existing test, or switches a test off |
no-secrets | A line that prints a key, a token, a secret or a password |
Why three jobs, and not one? Inside one job, the first failing step stops the steps after it. Say all three checks were steps in one job, and a test failed. The other two checks would never run, so nobody would learn that a test was also edited and a key was also printed. Each job runs on its own. So with three jobs, all three problems are reported.

Figure 15.13. One job stops at the first failure. One job per check lets every problem report.
Each check catches one common mistake, and no more. Review covers what they miss. And the files that run the checks have a named owner (15.9), because a check is only as strong as those files.
Which checks stop a merge?
Only the ones the repository requires. Every check is one of two kinds.
- An advisory check is the smoke detector. It only reports, and the merge button still works.
- A blocking check is the circuit breaker. The pull request cannot join
mainuntil the check passes.
The check does not decide which kind it is. The repository's settings on GitHub decide.
How does a check become required?
A person with the right to change the repository's settings turns on a rule for main, and names the check in it. The rule is "Require status checks to pass before merging". A check named there is a required check: a merge waits until it has passed. This is the wire from the detector to the breaker. The check is the same. Now it stops the merge.
Three more rules sit beside that one:
- "Require a pull request before merging" stops a change that goes straight to
main, from a person or an agent. - "Require conversation resolution" stops a merge while a review thread is still open. An AI review is advisory by default (15.7), and this rule is the simplest way to make its open findings stop a merge.
- "Require approvals" stops a merge without the people that 15.9 names.
At work. Ana makes all three jobs required on main, with conversation resolution on. The agent-speedup pull request shows three red marks, one per job. The tests fail on the cutoff case. The test comparison fails on the edited expected value. The secret check fails on the debug line that prints the key. The merge button is gray. Nobody had to read the diff to stop it, though someone still will, to learn why an agent did this.
Try it
In your practice folder from 15.1, the checks file is a stub: it has one job that only prints a line. You are reading a checks file here, not code. Its checks run the TypeScript side of the project, whichever language you read in. Fifteen minutes.
- Send: "Show me the workflow file in this project, and tell me in plain words when it runs and how many jobs it has. Change nothing."
- Predict in your note. You will split the file into two jobs, one for the type check and one for the tests. If the type check fails, will the tests still report? And will either job stop a merge today?
- Send: "Make a new branch practice-ci. Change the workflow so it has two jobs, typecheck and tests. Each job does four things in order: fetch the code, set up Node 24, install the packages from the lock file, and run one check. The check in the first job is the type check. The check in the second job is the tests. Change nothing else. Show me the file before you save it." In the file it shows, look for two names under
jobs:, which aretypecheckandtests. Under each name, look for four steps, the last one arunline with the check. Then approve. - Send: "Commit it, and switch back to main."
What you should see. The stub runs on pull requests to main, and its one job only prints a line. After your change, the file has two jobs, typecheck and tests. Each job reports on its own, so a failing type check does not hide the tests. Nothing was blocked, and that is the right result. On your computer this file only describes the checks. They run, and can be made required, only on GitHub. Making one required is a setting there. You turn it on, and see a merge blocked, in Lab 15.
The operating rule: make every check a machine can run a required check, and never mistake an advisory report for a gate.
Other words you will meet
| Word | What it means |
|---|---|
| Workflow | GitHub's name for the checks file. It lives in .github/workflows/ |
| Continuous integration, or CI | Running checks like these on every change |
| Branch protection | GitHub's name for the set of rules on a branch such as main1 |
| Ruleset | The newer form of branch protection2 |
permissions: contents: read | A line in the workflow. With it, the workflow's token can read the code and do nothing else |
| Failing closed | A check that cannot do its job fails. Brightline's scripts fail when they cannot find the branch to compare with, or a folder to search |
The tests-changed label | A marker a person adds to a pull request by hand when a test has to change. tests-unchanged then lets it through, and the team asks for a written reason and a named owner's approval |
| An AI review as a gate | Three ways: require conversation resolution, add a required job that fails on an Important finding, or run a security review in your own workflow with your own step that fails on findings |
| Repository secret | Where a key lives. GitHub stores it and gives it to the workflow when it runs. Never commit a key to a file3 |
| Fork | An outside copy of the repository. GitHub gives no secrets to a workflow started from a fork |
pull_request_target | A way of starting a workflow that gives it your secrets. Never use it to build or run a pull request's code, which is untrusted4 |
In your tool: the details
What each product can block, and how it runs in your own CI. You need none of this for the practice above.
What blocks. Code Review never approves or blocks. Its check run, Claude Code Review, ends as neutral, never as a failure. After some pushes it ends as skipped and keeps the earlier result. To block on its findings, your own workflow reads the severity counts from the check run with gh api and fails on an Important finding, or you require conversation resolution.5
In your own CI. The Claude Code GitHub Action, anthropics/claude-code-action@v1, runs Claude in your workflows. It is set up with /install-github-app or by hand, with an API key or a Claude subscription token stored as a repository secret. Its default trigger, @claude, also fires on Code Review's @claude review, so set its trigger_phrase to something else if you use both.6
The security review Action. anthropics/claude-code-security-review comments on pull requests and reports a findings count. It has no setting to fail the job on findings, so a blocking security review needs your own step that fails when that count is above zero. Its README says it is not hardened against prompt injection and should review only trusted pull requests.7
What blocks. OpenAI's documentation names no setting that makes a Codex review block a merge or count as an approval.8
In your own CI. openai/codex-action@v1 runs Codex in a GitHub workflow, with the OpenAI key stored as a repository secret. Only users with write access can run it by default. OpenAI warns to treat pull request text as untrusted input.9
What blocks. OpenCode has no reviewer of its own, so nothing it does blocks a merge.
In your own CI. OpenCode 2.2.0, October 27, 2026, stopped publishing its GitHub Action, and its changelog tells users to remove it from workflows.10 opencode run sends a prompt without the interactive interface, so a review can run in a script or your own CI step.11
Keep it read-only. Version 2 sets permissions as an ordered list of rules with allow, ask or deny, and the last matching rule wins. For a reviewer, deny edits and allow only read commands such as git diff.12 OpenCode does not sandbox the agent. A review run in CI has whatever the CI machine gives it, so give it a read-only token and no secrets it does not need.13
Check yourself
Question 1 / 10 · drawn from 11
0 answered
Which setting stops a merge while a review thread is still open?
Sources
- Events that trigger workflows, GitHub.↑
- Read and request reviews on a pull request, Anthropic.↑
- Claude Code GitHub Actions, Anthropic.↑
- claude-code-security-review, Anthropic.↑
- Codex in GitHub, OpenAI.↑
- Codex GitHub Action, OpenAI.↑
- Changelog, OpenCode.↑
- CLI, OpenCode.↑
- Permissions, OpenCode.↑
- Security policy and advisories, OpenCode.↑
- Owner
- Panaversity