Required status checks in Git - Commands & Configuration

Introduction

When working with teams on code, you want to make sure that certain tests or checks pass before merging changes. Required status checks help by blocking merges until these checks succeed, keeping the code safe and stable.

When you want to ensure all automated tests pass before merging a feature branch.

When you need to enforce code review approvals before allowing merges.

When you want to prevent broken code from entering the main branch.

When multiple team members contribute and you want consistent quality control.

When using continuous integration tools that report build or test results.

Commands

Push your feature branch to the remote repository so that status checks can run on it.

Terminal

git push origin feature-branch

Expected Output

Enumerating objects: 5, done.

Counting objects: 100% (5/5), done.

Delta compression using up to 8 threads

Compressing objects: 100% (3/3), done.

Writing objects: 100% (3/3), 350 bytes | 350.00 KiB/s, done.

Total 3 (delta 2), reused 0 (delta 0)

remote: Resolving deltas: 100% (2/2), completed with 2 local objects.

To https://github.com/example/repo.git

   abc1234..def5678  feature-branch -> feature-branch

Check the current branch and status locally before creating a pull request.

Terminal

git status

Expected Output

On branch feature-branch

Your branch is up to date with 'origin/feature-branch'.

nothing to commit, working tree clean

Create a pull request on GitHub from your feature branch to the main branch. This triggers required status checks configured on the repository.

Terminal

gh pr create --title "Add new feature" --body "This adds a new feature with tests."

Expected Output

Creating pull request for feature-branch into main

https://github.com/example/repo/pull/42

→

--title - Sets the pull request title

→

--body - Adds a description to the pull request

View the status of required checks on pull request number 42 to see if all tests have passed.

Terminal

gh pr checks 42

Expected Output

Check suite for PR #42

✔️ build

✔️ test

✔️ lint

All required status checks have passed.

Key Concept

If you remember nothing else from this pattern, remember: required status checks stop code from merging until all tests and reviews pass, protecting your main branch.

Common Mistakes

Pushing code without creating a pull request to trigger status checks.

Status checks only run on pull requests, so skipping this step means no checks run.

Always create a pull request after pushing your branch to start the checks.

Ignoring failed status checks and merging anyway.

This can introduce broken or untested code into the main branch.

Wait for all required checks to pass before merging.

Not configuring required status checks in the repository settings.

Without configuration, checks won't block merges even if they run.

Set required status checks in the repository settings on GitHub or your Git server.

Summary

Push your feature branch to the remote repository to start the process.

Create a pull request to trigger required status checks like tests and builds.

Use commands to check the status of these checks before merging.

Required status checks help keep your main branch stable and error-free.