github-pages-deploy-action
🚀 Automatically deploy your project to GitHub Pages using GitHub Actions. This action can be configured to push your production-ready code into any branch you'd like.
A GitHub Action that automatically publishes a build folder to GitHub Pages on every push, no extra credentials needed, just point it at your output folder and which branch to deploy to.
This is a GitHub Action, meaning it is a piece of automation that runs inside GitHub's own infrastructure whenever something happens in your repository, such as a new code push. Specifically, this action takes a folder from your repository and publishes it to GitHub Pages, the free static website hosting that GitHub offers to every repository. You point the action at the folder where your built website lives (for example, a folder called "build" that your JavaScript project produces), and it pushes those files to the branch GitHub Pages reads from, typically called "gh-pages".
To use it, you add a small configuration file to your repository under a ".github/workflows" folder. The example in the README shows a workflow that checks out your code, runs your build command, and then calls this action with two settings: which branch to deploy to, and which folder to push. The action handles creating that branch if it does not already exist, and it authenticates using GitHub's built-in security token so you do not need to set up separate credentials for a basic deployment.
The action supports deploying to a different repository than the one it runs in, which is useful for organizations that keep source code and the published site in separate places. It also works with GitHub Enterprise installations. For teams that want finer control, there are optional settings for custom commit messages, clean deployments that wipe the target branch before deploying, and single-commit mode that squashes the history on the deployment branch.
Beyond the GitHub Action itself, the package is also published to npm so developers can call the same deployment logic from their own Node.js scripts or custom actions. The project is written in TypeScript and has both unit tests and integration tests running in CI.
Where it fits
- Automatically publish your React, Vue, or static site build folder to GitHub Pages every time you push to main.
- Deploy documentation generated by tools like Docusaurus or MkDocs to a gh-pages branch without any manual steps.
- Publish a built website from one repo to a separate GitHub Pages repo for organizations that keep source and site apart.
- Call the same deploy logic from a Node.js script using the npm package outside of GitHub Actions.