Repolode
Submit
peaceiris

peaceiris/actions-gh-pages

A GitHub Action that deploys static site build output to a GitHub Pages branch from your workflow.

View on GitHubWebsite
Stars
5,369
Forks
448
Open issues
95
Last commit
20 hours ago

What is it?

This GitHub Action publishes the contents of a build output directory, such as ./public or ./out, to a branch used by GitHub Pages, gh-pages by default. It works with any static site generator that produces plain files, including Hugo, MkDocs, Gatsby, mdBook, Next.js, Nuxt and VuePress, so the deployment step can be added after the build step in an existing workflow.

Authentication can use the automatically created GITHUB_TOKEN for the current repository, an SSH deploy key, or a personal access token. The personal token or deploy key is needed to publish into another repository through the external_repository option. Other options cover the target branch, a destination subdirectory, excluding files, adding a CNAME file, controlling Jekyll processing, keeping existing files, force-orphan branches, commit author and message, and creating Git tags.

The action runs on Linux, macOS and Windows runners, and supports GitHub Enterprise Server from version 2.22.6.

Key features

  • 01Deploys any static build output directory to a GitHub Pages branch.
  • 02Supports GITHUB_TOKEN, SSH deploy keys and personal access tokens.
  • 03Can publish to a separate external repository.
  • 04Options for CNAME files, Jekyll bypass and excluding files from deployment.
  • 05Can keep existing files or create a single-commit orphan branch.
  • 06Runs on Linux, macOS and Windows runners.

Use cases

  • Publishing a Hugo or MkDocs documentation site automatically on every push to main.
  • Deploying a Next.js or Nuxt static export to GitHub Pages from CI.
  • Publishing a public site from a private source repository using a personal access token.
  • Scheduling regular rebuilds and deployments of a generated site.

Quick start

  1. 1

    Add the workflow file .github/workflows/gh-pages.yml and push it to the default branch

  2. 2

    Use the deploy step to publish your build output directory

    uses: peaceiris/actions-gh-pages@v4

Things to know

  • Requires the repository's Pages settings to be configured before the first deployment with GITHUB_TOKEN.
  • Deploy keys are needed for Windows runners, since the deploy_key option does not work there.

In collections

Testing frameworks & test automation toolsStatic site generators & documentation tools

Topics

#github-actions#github-pages#static-site#deployment#ci-cd#ssg#actions#gatsby#hugo#mdbook

FAQ

What is actions-gh-pages?
A GitHub Action that deploys static site build output to a GitHub Pages branch from your workflow. This GitHub Action publishes the contents of a build output directory, such as ./public or ./out, to a branch used by GitHub Pages, gh-pages by default. It works with any static site generator that produces plain files, including Hugo, MkDocs, Gatsby, mdBook, Next.js, Nuxt and VuePress, so the deployment step can be added after the build step in an existing workflow.
Is actions-gh-pages free to use? What license does it have?
actions-gh-pages is open source under the MIT license. Check the license terms before using it in commercial products.
Is actions-gh-pages still maintained?
Actively maintained. The last commit to actions-gh-pages was on Nov 6, 2026.
What can I use actions-gh-pages for?
Publishing a Hugo or MkDocs documentation site automatically on every push to main. Deploying a Next.js or Nuxt static export to GitHub Pages from CI. Publishing a public site from a private source repository using a personal access token. Scheduling regular rebuilds and deployments of a generated site.
How do I install actions-gh-pages?
Add the workflow file .github/workflows/gh-pages.yml and push it to the default branch Use the deploy step to publish your build output directory: uses: peaceiris/actions-gh-pages@v4
Where can I get actions-gh-pages?
The source code and installation instructions are on GitHub: https://github.com/peaceiris/actions-gh-pages

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects