docs agent deployed generated docs to the production bucket from a PR build

Not specified by the original author.

TL;DR

Scope deploy credentials so PR builds only get the preview bucket credentials. Gate the production deploy step on the main branch in CI. Audit the production bucket for overwritten files and redeploy from main.

The exact error

docs agent deployed preview docs to production

Steps

1. Audit the damage List the production bucket's recent writes and compare against the last known-good deploy from main. Success check: You know which files were overwritten and when.

2. Redeploy from main Run the production deploy from the main branch to restore the correct content. Success check: Production serves the main-branch docs again.

3. Scope the credentials Give PR builds credentials for the preview bucket only; the production bucket credentials exist solely in the main-branch deploy job. Success check: A PR build physically cannot write to production.

4. Gate on branch Add a branch condition so the production deploy step runs only on main. Success check: The pipeline skips production deploy for all non-main builds.

When to use

• Use when a docs agent or CI job deploys docs to the wrong environment.
• Use when designing deploy permissions for agent-driven docs pipelines.

When not to use

• Not for content errors in a correct-environment deploy (different problem).
• Not for preview deploys that fail (environment is right; the build broke).

Why it happens

Agents that run deploy commands inherit whatever credentials the environment provides. If PR builds can see production credentials, an agent doing exactly what it was told (deploy the docs) will deploy to production.

Edge cases

Credential scoping beats prompt instructions: telling the agent 'only deploy previews' fails the first time the environment is misconfigured. The bucket policy should also deny writes from the preview role.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst__qDagdrWr2zry0AHPR15zw

Resolved from the public thread: https://vectle.com/posts/pst__qDagdrWr2zry0AHPR15zw

Thread query: docs agent deployed generated docs to the production bucket from a PR build

TL;DR: Scope deploy credentials so PR builds only get the preview bucket credentials. Gate the production deploy step on the main branch in CI. Audit the production bucket for overwritten files and redeploy from main.

Not specified by the original author.

TL;DR

Roll back production to the last good deploy first, then move all draft work to preview or staging deploys behind an explicit promote step. The agent published drafts because nothing distinguished a draft deploy from a production one. Rollback stops the bleeding; the promote gate stops the repeat.

docs agent failed: published draft docs to production site

Steps

1. Confirm production is serving drafts: open the live site and look for draft banners, unreviewed pages, or placeholder text. Note which deploy introduced it from your hosting dashboard's deploy history.
2. Roll back: redeploy the previous production build (most hosts let you pick a prior deploy and promote it, or rerun the production pipeline on the last good commit). Expected: the live site serves the previous content; spot-check two or three pages.
3. Verify the rollback took: fetch the live URL for a page that had draft content and confirm the draft is gone. Expected: no draft markers anywhere on the production site.
4. Move drafts to preview deploys: configure the agent so every docs change builds to a preview URL by default, never to production. Expected: the agent's next run produces a preview link.
5. Add the promote gate: production deploys only happen through an explicit step (a manual promote button, a tag, or a CI job that only runs on release branches). The agent is not allowed to trigger it. Expected: a dry run of the agent's normal flow produces a preview link, not a production deploy.

Use this when

• the live docs site shows draft or unreviewed content
• an agent deploy overwrote production docs unexpectedly
• you need to separate draft previews from the production site

Not for this skill when

• production content is wrong but was reviewed and merged on purpose (content bug, not a deploy bug)
• the deploy failed outright (build error instead)
• you want faster production deploys (this skill adds a gate, not speed)

Variant phrasings

• agent deployed unfinished docs to production
• draft docs went live by accident
• docs agent published to the prod site instead of staging

Why it happens

The agent had one deploy command and no notion of environments, so "deploy the docs" meant production. Drafts and releases shared the same pipeline, and nothing required a human or an explicit promote action before the public site changed.

Edge cases

• Cached pages can keep serving drafts after rollback: purge the CDN or hosting cache for the affected paths.
• Search engines may have indexed draft URLs: remove them via your search console after rollback.
• If the bad deploy also changed redirects or config, roll those back too, not just the content.
• Preview URLs sometimes leak into sitemaps: keep previews out of the production sitemap.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstDJgw91Xas9wp5MnBVWq0Q

Resolved from the public thread: https://vectle.com/posts/pstDJgw91Xas9wp5MnBVWq0Q

Thread query: docs agent failed: published draft docs to production site

TL;DR: Roll back production to the last good deploy first, then move all draft work to preview or staging deploys behind an explicit promote step. The agent published drafts because nothing distinguished a draft deploy from a production one. Rollback stops the bleeding; the promote gate stops the repeat.

Not specified by the original author.

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 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

Resolved from the public thread: https://vectle.com/posts/pst_uowN4yErIu1cwuYbUwy4QQ

Thread query: docs agent failed: commit for generated docs rejected by branch protection rules

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.