This guide takes you through how to deploy a Node app with GitHub Actions so that the static output can be served as GH Pages. This works well for Single-Page Applications, such as if using React or Vue.

Submission category

This is my submission to GitHub Actions Hackathon under DIY Deployments.

How it works

1. My workflow will be triggered by any pushes to master and any Pull Requests against master. Any changes to the docs directory will not trigger the workflow, as there is no point in rebuilding the app in that case.
2. The GitHub Actions environment already includes Node and Yarn, so if you don't care about the specific versions needed, you can leave out setup steps. For more control, see Node workflows.
3. There are shell steps to install NPM dependencies, run checks (linting and formatting) and then build the app. You can use npm or yarn in the steps.
4. The final step uses an Action which will take the unversioned output in the dist directory and commit it to the root of the gh-pages branch. For Vue, dist is typical, while React projects use build.

The repo should configured to serve the gh-pages branch as a site.

Sample YAML file

Create a workflow as .github/workflows/main.yml in your repo.

name: Deploy GH Pages

on:
  push:
    branches: master
    paths-ignore:
      - "docs/**"

  pull_request:
    branches: master
    paths-ignore:
      - "docs/**"

jobs:
  build-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@master
        with:
          persist-credentials: false

      - name: Install 🔧
        run: yarn install    # OR npm install

      - name: Lint 🧐
        run: yarn lint:check # OR npm run lint:check

      - name: Build 🏗️
        run: yarn build      # OR npm run build
        env:
          NODE_ENV: production

      - name: Deploy to GH Pages 🚀
        if: ${{ github.event_name != 'pull_request' }}
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: dist

Note that you don't have to generate or set a token - a token will be generated for you by GH Actions. A token which only has access to the current repo and no human will need to interact with the token.

After committing the above file, check your Actions tab and wait for the workflow to run.

After it is successful, go to repo settings and enable Pages against the root of your gh-pages branch, to serve that as a GH Pages site.

Then check the Environment section to see it deployed.

Note also that the actual deploy step only runs against master commits directly and not on a Pull Request. So you can safely have your test and build steps run against a feature branch on a Pull Request for quality control, without actually deploying anything until the PR gets merged.

Workflows in use

Vue

I have a vue-quickstart repo which was generated with Vue CLI and then extended with documentation, CI/CD, and demo site.

MichaelCurrin / vue-quickstart

Starter template for a Vue 2 site - including docs and CI deploy to GH Pages

Vue Quickstart

Starter template for a Vue 3 site - including docs and CI deploy to GH Pages

Preview

Use this project

After you've looked at the demo screenshot and site, you are welcome to create your own using the template button. This will copy this project and add it to your repos (no forking needed, but please star the original repo).

Documentation

How to install and run the app locally and deploy it to GH Pages

About

What is Vue?

Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

Why not React?

Vue is intended to be more beginner-friendly (I agree it is) and the vue repo has more GH stars than the react repo, if that is any indication of adoption by the community.

Vue is open-source and was created by one person originally. React was created at Facebook.

Resources

Need are some resources…

View on GitHub

See main.yml there.

React

I did the same thing for React:

MichaelCurrin / react-quickstart

Starter template for a React app - including docs, CI, and hosting ⚛ 📦

React Quickstart ⚛️ 📦

Starter template for a React app - including docs, CI, and hosting

Preview

Create a new React app

Use this project as a template:

If you need something more minimal, see this Minimal app recipe.

Documentation

To install, run and deploy the app, see this project's docs:

To learn how to use this project and see how a React project works, see the Template notes section of the docs.

License

Released under MIT by @MichaelCurrin.

This project is based on the template from the React CLI. I have added my own docs, the deploy flow, made minor changes to the app, plus some additions to components.

View on GitHub

See main.yml there.

Resources

On Code Cookbook

I have a ton of GH Actions workflows you can browse here:

• Workflows | Code Cookbook

On my Dev Resources site

• Node resources
• GH Actions resources
• GH Pages resources
• Vue resources
• React resources

More template repos

No Node or CI needed here! These use CDN URLs to load React or Vue in the browser and that static HTML gets served directly on GH Pages without a build step.

• react-frontend-quickstart
• vue-frontend-quickstart

Credits

Photo by Andrik Langfield on Unsplash