mkdocs gh-deploy: Publish MkDocs to Pages
mkdocs gh-deploy runs a build and force-pushes the result to the gh-pages branch so GitHub Pages serves it.
gh-deploy is the one-shot publish command for MkDocs. It commits the built site to a branch; in CI you need a token with push rights and, for versioned docs, the mike wrapper.
What it does
mkdocs gh-deploy builds the site, commits it to the gh-pages branch (configurable), and pushes to the remote. GitHub Pages then serves that branch. It rewrites the branch history, so the branch holds only the current build.
Common usage
mkdocs gh-deploy --force
# deploy to a specific branch and remote without pushing
mkdocs gh-deploy --branch gh-pages --no-history --dirtyOptions
| Flag | What it does |
|---|---|
| --force | Force-push, ignoring the remote branch state |
| --branch / -b <name> | Target branch (default gh-pages) |
| --remote-name <name> | Git remote to push to (default origin) |
| --no-history | Replace branch history with a single commit |
| --message <msg> | Commit message for the deploy commit |
| --dirty | Only rebuild changed pages (faster, less safe) |
In CI
On GitHub Actions, grant permissions: contents: write and use the built-in GITHUB_TOKEN; mkdocs gh-deploy --force then pushes cleanly. For multiple versions use mike deploy instead. Newer setups prefer the actions/deploy-pages artifact flow over pushing a branch.
Common errors in CI
remote: Permission to owner/repo.git denied or fatal: unable to access ... 403 means the token lacks write scope; add contents: write. Failed to deploy: ... Updates were rejected because the tip of your current branch is behind is fixed by --force. error: src refspec gh-pages does not match any means the branch does not exist yet; the first --force deploy creates it.