A GitHub Action to deploy static files to GitHub Pages, compatible with any static site generator.
peaceiris/actions-gh-pages is a GitHub Action that automates the deployment of static files to GitHub Pages. It solves the problem of manually building and pushing static sites by integrating directly into GitHub Actions workflows, supporting a wide variety of static site generators and offering flexible configuration options.
Developers and teams building static websites with generators like Hugo, Gatsby, Next.js, or MkDocs who want to automate deployment via GitHub Actions. It's particularly useful for those managing documentation, blogs, or project sites on GitHub Pages.
Developers choose this action for its robustness, extensive documentation, and compatibility with virtually any static site generator. It offers more configuration options than GitHub's official Pages action, such as external repository deployment, custom commit messages, and support for multiple authentication methods.
GitHub Actions for GitHub Pages 🚀 Deploy static files and publish your site easily. Static-Site-Generators-friendly.
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.
Supports three token types (github_token, SSH deploy keys, personal access tokens) for different use cases, including private repos and external repositories, as detailed in the Supported Tokens section.
Works seamlessly on all GitHub Actions runners (Linux, macOS, Windows), ensuring reliability across diverse development environments, as shown in the Supported Platforms table.
Offers advanced options like custom commit messages, CNAME file handling, Jekyll processing, and orphan branch support, allowing fine-grained control over deployments without manual intervention.
Includes comprehensive examples for popular static site generators (Hugo, Gatsby, Next.js, Docusaurus, etc.), making it easy to integrate into existing projects with minimal configuration.
Key options like destination_dir and exclude_assets are marked as beta with feedback requests in the README, indicating potential bugs or breaking changes that could disrupt workflows.
Deploying to external repositories requires additional token management (personal_token or deploy_key) and doesn't work with GITHUB_TOKEN, adding setup complexity compared to internal deployments.
First deployments with GITHUB_TOKEN require manual branch selection on GitHub settings, as admitted in the FAQ, which can be confusing for new users and delay automation.