Repolode
Submit
JamesIves

JamesIves/github-pages-deploy-action

A GitHub Actions action that automatically builds and deploys your project to GitHub Pages, pushing output to any branch such as gh-pages or docs.

View on GitHubWebsite
Stars
4,613
Forks
447
Open issues
6
Last commit
4 days ago

What is it?

GitHub Pages Deploy Action is a GitHub Actions step that publishes a folder from your workflow, such as a build output directory, to GitHub Pages. You choose the target branch, including gh-pages or docs, and the action creates that branch if it does not exist yet. It also supports cross-repository deployments and works with GitHub Enterprise.

The action is configured in the `with` section of a workflow file. The main required input is `folder`, the directory to deploy. Optional settings cover the target branch, commit message, git author, custom tokens or SSH deploy keys, and whether to clean stale files from the deployment branch. It can also run in dry-run mode, squash history into a single commit, and expose a `deployment-status` output for later steps.

It is intended for static sites and other projects whose built output can be served from a branch. The action runs on Ubuntu by default and needs write permission to repository contents.

Key features

  • 01Deploys any folder to any branch, including gh-pages and docs.
  • 02Supports cross-repository deployment using a personal access token.
  • 03Authenticates with the default GITHUB_TOKEN, a PAT, or an SSH deploy key.
  • 04Cleans stale files from the deployment branch while keeping excluded files.
  • 05Offers dry-run mode, single-commit history, and a deployment-status output.

Use cases

  • Publishing a static site built with a framework like React or Vue to GitHub Pages after each push.
  • Deploying documentation generated by a build tool to a docs branch.
  • Pushing build output from one repository into another repository's Pages site.
  • Deploying from a Windows build job by passing artifacts to an Ubuntu deploy job.

Quick start

  1. 1

    Add a workflow file that checks out the repo, builds the site, and deploys with the action

  2. 2

    Set the workflow permissions to contents: write and point folder at your build output

  3. 3

    In repository settings, choose Pages, then Deploy from a Branch, and select the deploy branch (usually gh-pages)

In collections

Testing frameworks & test automation toolsStatic site generators & documentation tools

Topics

#github-actions#github-pages#deployment#ci-cd#static-site#continuous-deployment#action#actions#cicd#continuous-delivery

FAQ

What is github-pages-deploy-action?
A GitHub Actions action that automatically builds and deploys your project to GitHub Pages, pushing output to any branch such as gh-pages or docs. GitHub Pages Deploy Action is a GitHub Actions step that publishes a folder from your workflow, such as a build output directory, to GitHub Pages. You choose the target branch, including gh-pages or docs, and the action creates that branch if it does not exist yet. It also supports cross-repository deployments and works with GitHub Enterprise.
Is github-pages-deploy-action free to use? What license does it have?
github-pages-deploy-action is open source under the MIT license. Check the license terms before using it in commercial products.
Is github-pages-deploy-action still maintained?
Actively maintained. The last commit to github-pages-deploy-action was on Nov 2, 2026.
What can I use github-pages-deploy-action for?
Publishing a static site built with a framework like React or Vue to GitHub Pages after each push. Deploying documentation generated by a build tool to a docs branch. Pushing build output from one repository into another repository's Pages site. Deploying from a Windows build job by passing artifacts to an Ubuntu deploy job.
How do I install github-pages-deploy-action?
Add a workflow file that checks out the repo, builds the site, and deploys with the action Set the workflow permissions to contents: write and point folder at your build output In repository settings, choose Pages, then Deploy from a Branch, and select the deploy branch (usually gh-pages)
Where can I get github-pages-deploy-action?
The source code and installation instructions are on GitHub: https://github.com/JamesIves/github-pages-deploy-action

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

Related projects