docs agent failed: auth token expired mid docs deploy to gh-pages

docs agent failed: auth token expired mid docs deploy to gh-pages

TL;DR

Generate a fresh deploy credential, store it where the deploy reads it, then rerun the deploy. The credential expired between runs, so the push to gh-pages got a 401 or 403. Fresh credential in the CI secret store, redeploy, and the site updates.

The error

docs agent failed: auth token expired mid docs deploy to gh-pages

Steps

1. Confirm it is expiry, not a bad credential. Read the deploy log for the failing step: a 401 or 403 on push to the gh-pages branch, after earlier pushes succeeded. Check the credential's expiry date in the provider settings.

Expected: you can point at the failed auth step and the past expiry date.

1. Create a new credential with the minimum scopes needed to push: contents write on that repo. Avoid broad scopes; the deploy only needs to update one branch.

Expected: the provider shows the new credential as active with an expiry date in the future.

1. Update the secret where the deploy reads it: the CI secret store or repo settings. Replace the old value in place and never commit the credential to the repo.

Expected: the secret's last-updated timestamp is now, and no credential value appears in git history.

1. Rerun the deploy, for example:

mkdocs gh-deploy

Expected: the push to gh-pages succeeds and the live site reflects the new docs.

Use this when

• a docs deploy that worked last week now fails with auth errors on push
• the failure is a 401 or 403 specifically on the gh-pages push step
• the deploy is scheduled and nobody touched its config recently

Not for this skill when

• the build fails before the push step (fix the build)
• the credential was never valid for this repo (check scopes and repo access)
• the deploy targets a different host, not gh-pages

Variant phrasings

gh-pages deploy 403 after credential expired

Same path: confirm expiry, mint a fresh scoped credential, update the secret, redeploy.

mkdocs gh-deploy authentication failed

Check whether the failure is on push (credential) or earlier (config or build).

scheduled docs deploy stopped working with no changes

Expiry is the first suspect for scheduled jobs; their credentials age silently.

Why it happens

Deploy credentials have fixed lifetimes. Scheduled docs deploys keep running on a timer, so the credential expires quietly between runs and the next deploy fails at the push step with no other warning.

Edge cases

• Fine-grained credentials can lose access to one repo while staying valid elsewhere. Verify write access on that exact repo, not just that the credential exists.
• A cached git credential on the agent machine can shadow the new value. Clear the credential helper cache before retrying.
• Some providers revoke credentials flagged as suspicious. Check for a revocation notice, not just the expiry date.
• If the deploy uses a deploy key instead of a credential, keys do not expire the same way; check whether the key was removed from the repo settings.

Provenance

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