GITHUB_TOKEN push to a protected branch rejected in CI

By Kaveh Alemi·Latchkey

Branch protection on the target branch blocks the push even though GITHUB_TOKEN has contents: write. Required pull requests, reviews, or status checks apply to github-actions[bot] too, so a direct push is rejected.

What this error means

A push step fails with "protected branch hook declined" or "Changes must be made through a pull request", not a plain permission error.

remote: error: GH006: Protected branch update failed for refs/heads/main.
remote: error: Changes must be made through a pull request.
! [remote rejected] main -> main (protected branch hook declined)

Common causes

Branch protection requires a pull request

The rule forbids direct pushes; even an authorized token must open a PR rather than push to the branch.

Required status checks or reviews are unmet

Required reviews or checks block the push until they pass, which a CI push cannot satisfy directly.

How to fix it

Open a pull request instead of pushing

1. Push to a new branch from CI.
2. Open a PR into the protected branch and let checks run.
3. Merge through the normal protected-branch flow.

- uses: peter-evans/create-pull-request@v6
  with:
    branch: automated-update
    title: Automated update

Allow a specific actor to bypass, deliberately

If a direct push is required, add the app/bot to the protection bypass list rather than weakening the rule for everyone.

# Settings > Branches > branch protection
# Allow specified actors to bypass required pull requests

How to prevent it

• Route automated changes through pull requests, not direct pushes.
• Grant explicit bypass only to the actor that truly needs it.
• Keep required checks satisfiable by the automated flow.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions