docusaurus deploy: Publish to GitHub Pages
docusaurus deploy builds the site and pushes it to the gh-pages branch, using the organizationName, projectName, and url from docusaurus.config.js.
The deploy command wraps build plus a git push to Pages. It relies on config fields being correct and, in CI, on a GIT_USER or token with push access.
What it does
docusaurus deploy runs a production build, then commits the output to the deployment branch (default gh-pages) of the repo derived from organizationName/projectName, and pushes it. url and baseUrl in the config must match the Pages URL or assets 404.
Common usage
GIT_USER=<github-username> npm run deploy
# use SSH instead of HTTPS auth
USE_SSH=true npm run deploy
# deploy to a custom branch
npx docusaurus deploy --deployment-branch gh-pagesOptions
| Env / flag | What it does |
|---|---|
| GIT_USER | GitHub username used for the push (HTTPS) |
| USE_SSH=true | Push over SSH instead of HTTPS |
| DEPLOYMENT_BRANCH | Branch to publish to (default gh-pages) |
| --skip-build | Deploy an existing build without rebuilding |
| organizationName / projectName | Config: identify the target repo |
In CI
Prefer the actions/deploy-pages artifact flow over docusaurus deploy in Actions, since it avoids managing a push token. If you do use deploy, set GIT_USER and provide a token with contents: write. Double-check baseUrl is /<repo>/ for project Pages sites.
Common errors in CI
Please set the GIT_USER environment variable, or explicitly specify USE_SSH instead! means neither auth method was configured. A deployed site with unstyled pages or 404 assets almost always means a wrong baseUrl. remote: Permission ... denied or 403 means the token lacks push rights.