Automating Code Review: What to Delegate to Machines

how to automate code review

Wondering how to automate code review? You can hand formatting, tests and required status checks to machines, and keep people for design and intent. Start by making checks mandatory on your protected branch.

Automated review is a stage of delivery, so read what is ci/cd first if the terms are new.

Item Value
How recently a required check must have passed During the past seven days
Check statuses that count as successful success, skipped, neutral
Workflow events whose job checks are evaluated on a pull request Six events, from push to deployment_status
Extra trigger a merge queue needs for Actions checks merge_group
Result of a required workflow skipped by path filtering Check stays Pending and blocks merging

These figures come from the GitHub Docs page Troubleshooting required status checks. Platform rules can change, so check the source before you rely on them.

What to hand to machines and what to keep for people

Machines are best at questions with a definite answer: does the code build, do the tests pass, does it follow the agreed style? Those questions belong in automated checks, not in a reviewer’s comments.

A good first list of jobs to delegate:

  • Formatting and style rules, so nobody argues about them in a pull request.
  • Build and test results that return a clear pass or fail.
  • Policy checks, such as a scan that must come back clean before merge.

People should keep what a script cannot judge. That means whether the change solves the right problem, whether the design fits the codebase, and whether the names will make sense to the next reader. Treat this human judgement as the scarce resource and spend it where it counts.

Mapping each check to a stage is easier if you know the ci/cd pipeline stages your team already runs. The cultural side, such as who owns quality, is covered in our explainer on what is devops.

Make automated checks required on protected branches

A check that only advises is easy to ignore. On GitHub, a required status check turns it into a gate on a protected branch. Per GitHub Docs, protected branches are available in public repositories with GitHub Free and GitHub Free for organizations.

When a required check fails, a push to the protected branch is rejected. The error looks like “GH006: Protected branch update failed”, followed by a line naming the failing check, as shown in the troubleshooting page.

how to automate code review Industrial robot
A jointed robotic arm stands inside an industrial workspace.

Two rules shape how the gate behaves. A required check must have completed successfully during the past seven days, and it must pass on the latest commit, because checks from earlier commits do not satisfy the requirement. The successful statuses are success, skipped and neutral, according to the same GitHub page.

Why a required check can block a pull request that looks fine

Most blocked merges come from a short list of causes. Work through them in this order:

  1. Confirm the check passed on the latest commit, not an earlier one.
  2. If branch protection requires an up-to-date branch, merge or rebase the base branch into yours.
  3. Look for a check and a commit status with the same name. When that name is required, both must pass.
  4. Check which event triggered the workflow run, as explained below.
  5. Verify the check came from the app your rule expects.

The event matters more than people expect. For checks created by workflow jobs to be evaluated on a pull request, the run must be triggered by push, pull_request, pull_request_review, pull_request_target, deployment or deployment_status. A workflow triggered by workflow_dispatch on the head branch shows nothing in the pull request’s checks section, even if it passes. This restriction applies to workflow jobs, not to checks created by an external GitHub App, per GitHub Docs.

A protected branch can also require a status check from a specific GitHub App. If the merge box says the required check was not set by the expected app, find out which app actually reported it.

Handling skipped checks and merge queues

Skipped checks are the sneakiest trap in automated review. What happens depends on why the check was skipped:

  • A workflow skipped by path filtering, branch filtering or a commit message leaves its checks in a Pending state, which blocks merging.
  • A job skipped by a conditional reports Success.
  • A job that depends on a failed job is skipped and may not block merging. Use always() with needs for required checks that depend on other jobs.

GitHub’s example is a workflow that runs only when a pull request changes files in a scripts folder. A pull request that only changes a file in the repository root never triggers it, so a required build job leaves the pull request waiting. The docs advise you to avoid requiring workflows that can be skipped.

Merge queues add one more rule. If a queue requires a GitHub Actions check, add the merge_group event as a trigger next to pull_request. Without it, the status check is never reported and the merge fails, as the same page explains.

A sensible rollout order

Do not switch everything on at once. A staged rollout keeps trust in the checks high, which is what makes people respect them.

  1. Begin with fast, deterministic checks such as formatting and tests, and let them report without blocking.
  2. Once a check is reliable, make it a required status check on the protected branch.
  3. Avoid making a required check out of a workflow that path or branch filters can skip.
  4. Add the merge_group trigger before you turn on a merge queue.
  5. Tell reviewers that style and test failures are no longer their job, so they can focus on design and intent.

This site is an independent educational resource. GitHub is named only as a neutral example of a platform that documents these behaviours.

Frequently asked questions

Can automation replace human code review?

Show answer

No. Machines answer pass or fail questions well, but they do not judge design or intent. Use automation to clear the routine findings so reviewers can spend their time on the rest.

Does a skipped check count as passing?

Show answer

Skipped is listed as a successful status in GitHub Docs. A required workflow skipped by path filtering is different: its checks stay Pending and block merging.

How long does a passing required check stay valid?

Show answer

GitHub Docs say a required status check must have completed successfully during the past seven days. It also has to pass on the latest commit.

Do I need the merge_group event?

Show answer

Yes, if a merge queue requires a GitHub Actions check. The event is separate from pull_request and push, so add it to your workflow triggers.