## 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
```text
generated docs commit rejected by branch protection
```

## Steps
1. **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.
2. **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.
3. **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.
4. **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