Deploy to GitHub Pages with GitHub Actions

README.md

GH Pages deploy

Deploys for static sites or web apps made easy with GitHub Actions

A generic but elegant CI flow for deploying a site to Github Pages - this is triggered on a push to master and runs on Github Actions - docs.

This workflow is targeted at a static site like Hexo or a single-page applciation like React project. It doesn't matter what the language is as long as your build steps results in a public directory which can be served on Github Pages.

Show me the workflow

Skip ahead to the main.yml workflow file.

About

The flow here is a generic but eleganic build and deploy flow. It doesn't even mention Hexo specifically.

It works great - see it here in action:

• Hexo
  • michaelcurrin.github.io/hexo-quickstart repo with workflow file as in this gist.
• React project
  • MichaelCurrin/react-create-app-quickstart repo with workflow file.

How to add to your project

Note that all edits must be done on your master branch and the site will be committed to the gh-pages branch for you.

1. Copy the YAML file content to your project at this path. Please keep the reference linking back to this repo.
   • .github/workflows/main.yml
2. Customize the build steps.
   • Such as change yarn to npm. Or use pip or use make commands.
3. Optionally add a test step.
   • For example:

     - name: Test 🚨
       run: yarn test

4. Change the publish_dir value to match the location of your output directory. e.g. public, dist or build.
5. Commit the workflow file.
6. Check your Actions tab to see that it runs and is successful.
7. Setup GH Pages
   • Go to your Github repo's Settings and enable to Github Pages on your site. You need to switch to another setting and back to gh-pages, then your GH Pages URL will be shown.

Your GH Pages site is published and will be rebuilt whenever a commit is made to master.

No local deploy step needed! 🎉

main.yml

# Created by MichaelCurrin
# https://gist.github.com/MichaelCurrin/a698731096f78240f653faf9a9127cba

name: Build and deploy 

on:
  push:
    branches:
      - master

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@master
        with:
          persist-credentials: false
          submodules: true  # TODO remove this if not using submodules in Hexo

      - name: Install 🔧
        run: yarn install

      - name: Build 🏗️
        run: |
          yarn clean
          yarn build

      - name: Deploy to GH Pages 🚀
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: public

questions.md

Questions

Some questions I imagine might come to might when reading this gist, which I have answers for:

What is the submodules parameter for?

I added submodules: true specifically for Hexo themes. If not using Hexo, you can remove the line.

My preference is to use submodules to keep the history simple and repo small, rather than cloning a repo inside a repo as per the standard Hexo flow.

Can you turn the workflow into an action?

Yes I have thought about packaging my workflow YAML as a Github Action available on Github, but it would be too restrictive.

I don't want to restrict the install and build flow - what if you want to use NPM or Python instead of Yarn? Or want to add a test step? Rather do those yourself as native build steps and not hide them inside an action. Also there are already actions dedicated to installing Yarn and Python projects so rather use one of those and chain together some actions.

The bulk of the complex happens in the peaceiris/actions-gh-pages repo which is already outsourced.

Why not another action?

There are several Github Actions available for deploying Hexo but they are complex and unnecessary dependencies.

They do a lot more like clearing Cloudfare cache.

And they take more details - one of them requires an email address.

For comparison:

• hexo-action
• hexo-github-action
• github-action-for-hexo