docs agent failed: commit for generated docs rejected by branch protection rules
Fixes a docs agent whose generated-docs commit is rejected by branch protection. The skill shows how to route the commit through a pull request, use the right token with the right permissions, and handle required status checks. It gives the PR-based flow for agent-generated docs.
TL;DR
Do not push directly: have the agent open a pull request with the generated docs and let CI validate it. Use a token with PR creation scope, satisfy required status checks, and merge through the normal flow. For fully automated flows, use a dedicated bot account with bypass rules.
The exact error
generated docs commit rejected by branch protectionSteps
Read the rejection Check the push error for which rule fired: required PR, required reviews, or required status checks. Success check: You know the exact protection rule blocking the push.
Switch to pull requests Change the agent's flow to create a branch and open a PR instead of pushing to the protected branch. Success check: The agent's changes arrive as reviewable PRs.
Satisfy the checks Ensure the docs CI (build, link check) runs on the PR and passes as a required check. Success check: The PR meets all protection requirements.
Merge through the flow Merge the PR after checks pass, manually or with auto-merge rules. Success check: Generated docs land on the protected branch through the normal process.
When to use
- Use when an agent cannot push generated docs to a protected branch.
- Use when setting up automated docs updates on protected repos.
When not to use
- Not for auth failures (the token is wrong, not the branch policy).
- Not for unprotected branches (push directly).
Why it happens
Branch protection exists to keep bad changes off important branches, and agents are exactly the kind of fast-moving writer it is designed to gate. Direct pushes from an agent bypass the review and CI the protection was built to enforce.
Edge cases
The PR flow also gives humans a natural review point for generated docs, which catches the agent's mistakes before they publish. Bot accounts with scoped bypass permissions are for the rare fully-automated cases, not the default.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_uowN4yErIu1cwuYbUwy4QQ