What it is

This project is a GitHub Action that deploys static files to GitHub Pages. It lives in the GitHub Actions ecosystem, is written in TypeScript, and is distributed under the MIT license. The action takes a build output directory from a workflow and publishes its contents to a branch that GitHub Pages serves, so a repository can go from committed source to a live site without any manual upload step. It is designed to pair with static site generators rather than to replace them, and the topic list names Hugo, MkDocs, Gatsby, mdBook, Next, Nuxt, and VuePress among the tools it is used alongside.

The concrete problem it solves is the gap between a build step and a published site. A generator produces a directory of HTML, CSS, and assets, but that directory still has to reach a branch that Pages will serve, with the right token, the right branch name, and the right subdirectory layout. This action performs that publish step inside a workflow, so the deployment is repeatable and versioned with the rest of the repository. It also handles the authentication choices that a plain push would require the author to wire up by hand, offering three token modes so that public and private repositories can both be deployed.

Key capabilities

• Deploys a chosen source directory to GitHub Pages through the publish_dir input, with ./public shown as the example.
• Supports three authentication methods: github_token, deploy_key, and personal_token, each covering private and public repositories.
• Publishes to a configurable branch through publish_branch, and can place output in a subdirectory with destination_dir.
• Filters which assets are published using exclude_assets.
• Writes a CNAME file for custom domains through the cname input.
• Can enable the built-in Jekyll processing with enable_jekyll.
• Runs on Linux, macOS, and Windows runners, and supports GitHub Enterprise Server above version 2.22.6.

Who uses it and how

• Teams building sites with Hugo, MkDocs, Gatsby, mdBook, Next, Nuxt, or VuePress who want the generated output published on every push.
• Maintainers of public repositories who use the automatically created GITHUB_TOKEN and need no extra secret configuration.
• Maintainers of private repositories who supply a deploy_key over SSH or a personal_token over HTTPS.
• Projects that publish documentation or a site into a subdirectory of an existing Pages branch.
• Organizations running GitHub Enterprise Server, where a technical user with write permissions may be needed because the runner's token might lack push rights.

Getting started

Add a workflow step that uses peaceiris/actions-gh-pages@v4 with github_token: ${{ secrets.GITHUB_TOKEN }} and publish_dir pointing at the build output. The action is also listed on the GitHub Marketplace.

When to use it — and when not to

The README directs readers to the official GitHub Pages Action first, and notes that GitHub Pages now uses Actions by default, so this action is a reasonable choice mainly when its specific inputs such as destination_dir, exclude_assets, or the deploy key mode are needed. A self-hoster must still configure repository Pages settings, and the first deployment with GITHUB_TOKEN requires manually selecting the publishing branch in the settings tab. Two further limits are visible in the facts: deploy_key support on Windows is marked as work in progress, and on GitHub Enterprise Server the runner token may not carry push privileges.

- name: Deploy
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public

name: GitHub Pages

on:
  push:
    branches:
      - main  # Set a branch name to trigger deployment
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    permissions:
      contents: write
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.110.0'

      - name: Build
        run: hugo --minify

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        # If you're changing the branch from main,
        # also change the `main` in `refs/heads/main`
        # below accordingly.
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

- name: Deploy
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public

- name: Deploy
  uses: peaceiris/actions-gh-pages@v4
  with:
    deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
    publish_dir: ./public