gh-pages deploy Command Reference

Publish a built static site to a gh-pages branch.

The gh-pages CLI pushes the contents of a build directory to a gh-pages branch (or any branch) so GitHub Pages serves it. In CI you authenticate the push with a token.

What it does

gh-pages commits a directory of built assets onto a target branch and force-pushes it to the remote, replacing the previous published state. GitHub Pages then serves that branch as a static site.

Common flags and usage

-d DIR: the directory to publish (required, e.g. dist)
-b BRANCH: target branch (default gh-pages)
-r REMOTE_URL: token-authenticated remote for CI
-m MESSAGE: commit message for the publish
-t: include dotfiles in the publish
--no-history: replace history with a single commit

Example

shell

- name: Publish to GitHub Pages
  run: |
    npx gh-pages -d dist \
      -m "ci deploy ${{ github.sha }}" \
      -r "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git"

In CI

Provide a token-authenticated remote with -r (using GITHUB_TOKEN or a PAT) so the force-push works without interactive credentials. Most modern Pages pipelines prefer the official actions/deploy-pages flow, but gh-pages remains a simple option for projects already wired to it.

Key takeaways

gh-pages force-pushes a built directory to a gh-pages branch for Pages.
Pass -r with a token-authenticated remote so CI can push non-interactively.
Consider the official actions/deploy-pages flow for newer pipelines.