GitHub Action to Deploy Static Assets to GitHub Pages

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/username.github.io) it will deploy to the master branch instead.

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.

Inputs

None.

Outputs

None.

Secrets

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). This token must be created with repo permissions in order to deploy to Github Pages. 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

name: Deployment

"on":
  - push
  - pull_request

jobs:
  deploy_ghpages:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/[email protected]
      - run: echo $GITHUB_SHA >> public/index.html
      - uses: maxheld83/[email protected]
        env:
          BUILD_DIR: public/
          GH_PAT: ${{ secrets.GH_PAT }}