# 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

```text
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.

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

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

4. Rerun the deploy, for example:

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