How to fix remote: error: GH006: Required workflow 'ci.yml' did not complete successfully in Git

First, identify exactly which workflow failed and why. Look at the complete error output:

# Example error output:
remote: error: GH006: Protected branch update failed for refs/heads/main.
remote: error: Required workflow "CI Tests / build" did not complete successfully.
remote: error: pre-receive hook declined

Then check the workflow status on GitHub:

1. Go to your repository on GitHub
2. Click the Actions tab
3. Find the workflow run that corresponds to your push or PR
4. Check the status: Failed, Skipped, Pending, or Success
5. Click into the failed job to see detailed logs

If the workflow shows as Skipped or Pending, the issue is with workflow triggers. If it shows as Failed, check the job logs for the actual error.

If the workflow failed due to actual errors (tests, build, lint), fix those issues first:

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

# Run linting locally
npm run lint
# or
flake8 .

# Fix any issues found, then commit and push
git add .
git commit -m "fix: resolve failing tests and linting issues"
git push origin your-branch

Check the workflow logs on GitHub for specific error messages:

1. Go to Actions tab
2. Click the failed workflow run
3. Expand the failed step to see the error output
4. Fix the underlying issue in your code

If the workflow was skipped, check if your workflow triggers are properly configured:

# .github/workflows/ci.yml
name: CI Tests

on:
  # Trigger on pull requests to main
  pull_request:
    branches: [main, master]

  # Required for merge queue support
  merge_group:
    types: [checks_requested]

  # Trigger on pushes to main
  push:
    branches: [main, master]

# Avoid path filtering if the workflow is required
# paths:
#   - 'src/**'  # This can cause the workflow to be skipped!

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm test

Important: If you use path filtering (paths:) and the workflow is required, it may be skipped when no matching files change. Either:

1. Remove path filtering from required workflows
2. Create a fallback workflow that passes when no changes match the path filter

The status check name must exactly match what's configured in branch protection. Check the naming:

For regular workflows:

jobs:
  build:  # This is the job name that appears as a status check
    runs-on: ubuntu-latest
    # ...

The status check name will be: build

For reusable workflows:

jobs:
  call-workflow:
    uses: org/repo/.github/workflows/reusable.yml@main

The status check name format is: <job name> / <reusable job name>

To check your branch protection settings:

1. Go to repository Settings > Branches
2. Click "Edit" on your branch protection rule
3. Look at "Require status checks to pass before merging"
4. Verify the check name matches your workflow's job name exactly

# List all status checks for a commit via GitHub CLI
gh api repos/{owner}/{repo}/commits/{sha}/status

If you renamed a workflow file or job, update the branch protection rules:

1. Go to repository Settings > Branches
2. Click Edit on the protection rule for your branch
3. Under "Require status checks to pass before merging":
- Remove the old workflow/job name
- Add the new workflow/job name
4. Save changes

Common renaming issues:

# Before: .github/workflows/test.yml
name: Tests
jobs:
  test:
    # ...

# After: .github/workflows/ci.yml
name: CI Pipeline
jobs:
  build-and-test:  # Job name changed!
    # ...

The status check name changed from test to build-and-test. Update branch protection accordingly.

Note: For organization-level rulesets, you need organization admin access to modify the ruleset configuration.

If the required workflow is enforced via organization rulesets, check the ruleset configuration:

1. Go to your organization's Settings
2. Under "Code, planning, and automation", click Repository > Rulesets
3. Find the ruleset targeting your repository
4. Check the "Require workflows to pass" section

Key considerations for ruleset workflows:

# Ruleset workflows must support these events:
on:
  pull_request:
  pull_request_target:
  merge_group:

# Other events like 'push' or 'workflow_dispatch' are ignored

Visibility requirements:
- Public workflows can run on any repository
- Internal workflows only run on internal and private repositories
- Private workflows only run on private repositories

If your workflow doesn't match the visibility requirements, it won't run.

Triggering workflow on existing PRs:
If a ruleset was added after your PR was opened, push a new commit to trigger the required workflow:

# Make a trivial change to trigger the workflow
git commit --allow-empty -m "chore: trigger CI workflow"
git push origin your-branch

If the branch is out of sync or status checks are stale, update your branch:

# Fetch latest changes from remote
git fetch origin

# If using strict status checks, rebase on the base branch
git checkout your-feature-branch
git rebase origin/main

# Or merge the base branch into your feature branch
git merge origin/main

# Push the updated branch
git push origin your-feature-branch --force-with-lease

For pull requests via GitHub UI:

1. Go to your pull request
2. Click "Update branch" button (if available)
3. Choose "Update with merge commit" or "Update with rebase"
4. Wait for status checks to run again

Important: When "Require branches to be up to date before merging" is enabled (strict mode), you must update your branch with the latest base branch changes before the checks will pass.

If your repository uses GitHub merge queues, ensure your workflow supports the merge_group event:

name: CI

on:
  pull_request:
    branches: [main]
  merge_group:  # Required for merge queue support!
    types: [checks_requested]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test

Without the merge_group event:
- Status checks won't trigger when PRs enter the merge queue
- The merge will fail because required checks aren't reported
- You'll see "Required workflow did not complete" errors

After adding the event, the workflow will run both:
1. When a PR is opened/updated (pull_request event)
2. When the PR enters the merge queue (merge_group event)

If you need to bypass the required workflow (use sparingly):

Option 1: Repository ruleset bypass list
If using organization rulesets, ask an admin to add you to the bypass list:

1. Organization Settings > Repository > Rulesets
2. Edit the relevant ruleset
3. Add your user/team to the bypass list
4. Use bypass only for emergencies with proper documentation

Option 2: Branch protection bypass
For repository-level branch protection:

1. Repository Settings > Branches
2. Edit the branch protection rule
3. Enable "Allow specified actors to bypass required pull requests"
4. Add yourself or your team

Option 3: Temporarily disable the rule
As a last resort, an admin can temporarily disable the rule:

# If you have admin access, use GitHub CLI
gh api -X PATCH repos/{owner}/{repo}/branches/main/protection/required_status_checks \
  -f strict=false \
  -f contexts[]=""

Warning: Bypassing required workflows should be rare and documented. It defeats the purpose of having quality gates.