How to fix remote: error: GH006: Protected branch update failed - required status check is failing in Git

First, identify exactly which checks are blocking the merge:

1. Go to your pull request on GitHub
2. Scroll to the "Checks" section at the bottom
3. Look for checks marked with a red X (failed) or yellow dot (pending)
4. Click on the failing check to see detailed logs

You can also check via the GitHub CLI:

# List all status checks for a PR
gh pr checks <PR_NUMBER>

# View detailed status
gh pr view <PR_NUMBER> --json statusCheckRollup

If a check shows "Expected" but never appears, the workflow isn't running at all.

If your CI pipeline is genuinely failing, fix the underlying issue:

For test failures:

# Run tests locally to reproduce
npm test
# or
pytest
# or
go test ./...

For linting/formatting failures:

# Fix linting issues
npm run lint -- --fix
# or
black .
# or
go fmt ./...

For build failures:

# Check build locally
npm run build
# or
cargo build

Commit the fixes and push to re-trigger the checks.

A common issue is mismatched check names. GitHub requires an exact match.

Find the actual check name:
1. Go to any recent PR where checks ran
2. Note the exact name shown (e.g., "build (ubuntu-latest)")
3. Names are case-sensitive and include matrix variables

Compare with branch protection settings:
1. Go to Settings > Branches > Edit your protection rule
2. Under "Require status checks to pass", see what's listed
3. The names must match exactly

For GitHub Actions, the check name comes from:

jobs:
  build:  # This becomes part of the check name
    name: "Build and Test"  # If specified, this overrides job ID
    runs-on: ubuntu-latest
    # Full check name might be: "Build and Test" or "build (ubuntu-latest)"

If names don't match, either:
- Update the workflow to produce the expected name
- Update branch protection to require the actual check name

If status checks show as "Expected" but never run, the workflow isn't triggering:

Check workflow triggers in your CI config:

# .github/workflows/ci.yml
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]  # Must include your target branch

Common trigger issues:
- Workflow only triggers on push but you need it on pull_request
- Branch pattern doesn't match (e.g., main vs master)
- Path filters exclude your changed files
- Workflow was added to a branch that doesn't exist in the PR's base

For external CI systems (Jenkins, CircleCI):
- Verify webhooks are configured in repo Settings > Webhooks
- Check the external system is receiving events
- Ensure the commit SHA matches what GitHub expects

Sometimes checks from previous commits become stale or stuck:

Re-run from the GitHub UI:
1. Go to the pull request
2. Click on the failing/stuck check
3. Click "Re-run jobs" or "Re-run all jobs"

Re-run via GitHub CLI:

# Re-run failed checks
gh run rerun <RUN_ID> --failed

# List recent workflow runs to find the ID
gh run list --branch <your-branch>

Force a new commit to trigger fresh checks:

# Empty commit to re-trigger CI
git commit --allow-empty -m "chore: trigger CI"
git push

Sync with base branch:

# Update from main to get fresh check context
git fetch origin main
git merge origin/main
git push

If using external services like Codecov, SonarCloud, or review apps:

Check service status:
- Visit the service's status page (e.g., status.codecov.io)
- Verify API tokens haven't expired
- Check the service is properly integrated with your repo

For Codecov issues:

# Ensure coverage is uploaded in CI
- name: Upload coverage
  uses: codecov/codecov-action@v4
  with:
    fail_ci_if_error: true  # Makes failures visible

For SonarCloud issues:
- Check project configuration at sonarcloud.io
- Verify the project key matches your repo
- Ensure quality gate conditions are reasonable

If the service is down, you may need to:
1. Wait for it to recover
2. Temporarily remove it from required checks (if you have admin access)
3. Contact the service's support

If a required check no longer exists (renamed workflow, removed CI system):

Remove from branch protection:
1. Go to Settings > Branches > Edit protection rule
2. Under "Require status checks to pass"
3. Click the X next to outdated check names
4. Add the new/correct check names
5. Save changes

Using GitHub Rulesets (recommended for organizations):
1. Go to Settings > Rules > Rulesets
2. Edit the relevant ruleset
3. Update "Require status checks to pass" with correct names
4. Rulesets can apply across multiple repos consistently

Via GitHub API:

# List current required checks
gh api repos/{owner}/{repo}/branches/main/protection/required_status_checks

# Update required checks
gh api repos/{owner}/{repo}/branches/main/protection/required_status_checks \
  -X PATCH \
  -f contexts[]="build" \
  -f contexts[]="test"

If automation needs to push despite failing checks (use sparingly):

Allow specific actors to bypass:
1. Go to Settings > Branches > Edit protection rule
2. Enable "Allow specified actors to bypass required pull requests"
3. Add the automation user or app
4. This also bypasses status check requirements

For GitHub Actions with elevated permissions:

# Use a PAT instead of GITHUB_TOKEN
- uses: actions/checkout@v4
  with:
    token: ${{ secrets.BYPASS_TOKEN }}

Warning: Bypassing status checks defeats their purpose. Only use for:
- Hotfix scenarios with proper oversight
- Automated releases that have already passed checks elsewhere
- Administrative corrections

Never bypass checks for regular development work.