peaceiris/actions-gh-pages: Deploy to GitHub Pages

actions-gh-pages publishes a built directory to the gh-pages branch for GitHub Pages.

A widely used way to deploy static sites by committing to a publishing branch. It supports GITHUB_TOKEN, deploy keys, and personal tokens.

Key inputs (with:)

• github_token: usually secrets.GITHUB_TOKEN.
• publish_dir: the built directory to publish, e.g. ./public.
• publish_branch: target branch (default gh-pages).
• cname: custom domain to write a CNAME file.
• keep_files: keep existing files instead of replacing.

Example workflow

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

On any runner

This action runs on any runner. Latchkey managed runners run it unchanged.

Key takeaways

• publish_dir points at your built output, not the source.
• Needs contents: write to push to the publishing branch.
• cname writes a CNAME file for custom domains.

Related guides