Skip to content
Deploy arbitrary static assets through GitHub Actions
Shell Dockerfile HCL
Branch: master
Clone or download
maxheld83 Merge pull request #20 from alex-page/patch-1
Title of Readme.MD says deploy to GitHub Actions instead of GitHub Pages
Latest commit 9270e8d Aug 12, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github try with PAT, not TOKEN Jan 30, 2019
public just index Jan 30, 2019
Dockerfile shorten name, add gif Jan 31, 2019
LICENSE Initial commit Jan 30, 2019 Update Aug 11, 2019
action-config.png fix readme as per #1 Jan 31, 2019
action-in-use.png fix readme as per #1 Jan 31, 2019
action-running.gif add gif, please Jan 31, 2019 Fix small typo in the commit message Mar 20, 2019

GitHub Action to Deploy Static Assets to GitHub Pages

Actions Status View Action

This action simply lets you deploy arbitrary folders of static content from your workflow's working directory (/github/workspace) to GitHub pages. This works by having your action instance git push your chosen asset folder (BUILD_DIR) to the gh-pages branch of your GitHub repository for the gh-pages branch to be served. If you are running this action inside an organization or user repository (named username/ it will deploy to the master branch instead.

Remember to add appropriate filter action as dependencies on this action to avoid deploying from all branches, as well as to avoid "infinite loops" where the deployment itself would trigger another run.

Remember that you may also have to adjust your repository settings.

Because this action deploys to separate, "deploy-only" branches, you can not use it if you want to deploy from a repo subdirectory such as docs/. In those cases you really don't need a GitHub Action, because you would be committing the build artifacts yourself. For details see the GitHub Pages Documentation.

There are already great GitHub actions to use static site generators and then deploy to GitHub Pages (for jekyll, jekyll, zola and surely many more to come). This action isn't that, though I've borrowed much of the git action from these works.

This action will not build anything, it just deploys.


Deployment to GitHub pages happens by git pushing to the gh-pages (or master) branch. To authorise this, the GitHub action needs a secret. For now, somewhat confusingly, the GITHUB_TOKEN available for every repo does suffice to push to gh-pages, but does not suffice to trigger a page build on GitHub, or even propagate the content to the GitHub content-delivery network.

You therefore have to create a custom Personal Access Token (PAT) much like you'd do for external services (say, Travis). You then have to paste this token into the GitHub UI as a secret under the name GH_PAT (repository settings/secrets) and call it in the action as in the below.

I've asked GitHub to streamline this process. The discussion is documented here.

Environment Variables

Just BUILD_DIR, the build directory relative to your repository root. You can also pass . if you want to push your repository root.



Example Usage

action "Deploy to GitHub Pages" {
  uses = "maxheld83/ghpages@v0.2.1"
  env = {
    BUILD_DIR = "public/"
  secrets = ["GH_PAT"]
You can’t perform that action at this time.