Custom GH Pages deploys made easy
Tags: githubpages, githubactions, ci, deploy
Published: 2020-06-28 22:09:02

---
title: Custom GH Pages deploys made easy
published: true
description: Use GH Actions to deploy your GH Pages site, for any tech stack
tags: githubpages,githubactions,ci,deploy
//cover_image: https://direct_url_to_image.jpg
---

> Use GH Actions to deploy your GH Pages site, for any tech stack

## Why GH Pages + GitHub Actions? 🤔

If you can relate to any these struggles, this post is for you:

- Do you like using free hosting services like [GitHub Pages](https://pages.github.com/)?
- Do you use a static site generator (like MkDocs or Jekyll 4 or VuePress) or a single-page JS app (like React/Vue/Gatsby) hosted on GitHub?
- Are you tired of having to run a deploy flow through a local command to get it to deploy to Github Pages? 
- Do you wish you didn't have to use an external tool like CircleCI or Netlify in order to deploy a repo hosted on GitHub?
- Do you want to a simple Github Actions flow that is easy to **reuse** across projects and languages?

In this post, I provide an elegant solution for _automagically_ building and deploying a static site or web app to **GitHub Pages** using **GitHub Actions**, using a repo hosted on GitHub.

A server-based web app that uses PHP or Node.js Express for example will not work on GH Pages. But if have a step to build assets and the assets can be served, then this is a good fit. Using GH Actions means that you can run that build step in the cloud to deploy your **Vue** or **React** app 💪.

If you need a beginner's guide to GH Actions or don't use GH Pages, then see my [Deploy pipeline tutorial](https://dev.to/michaelcurrin/intro-tutorial-to-ci-cd-with-github-actions-2ba8) post. 👩‍🏫

## My workflow 📃

Today I setup a JavaScript-based [Hexo](https://hexo.io) site for the first time. I added a CI flow using [GitHub Actions](https://github.com/features/actions) so that a push to the `master` branch will trigger a deploy to GitHub Pages. 

The way I set it up will work with just about any static site or JS single-page application. It uses generic steps to build a site and a generic action to publish to `gh-pages` branch for serving on Github Pages. So you can reuse this approach across JS-based project and even for a Hugo or Jekyll project.

I'd like to share my workflow file here as a gist of instructions.

- [gist.github.com/MichaelCurrin/a698731096f78240f653faf9a9127cba](https://gist.github.com/MichaelCurrin/a698731096f78240f653faf9a9127cba)

To be clear, this approach is **not** tied to an Action (some oti there are for GH Pages but specialize in Node, Yarn, React, MkDocs or Hexo, etc.). Just specify your shell build steps using NPM or Python or Jekyll. Whatever you would run locally in the shell to create a build output directory. Then use an generic action covered below to commit and deploy it to GH Pages.


## Build step 🏗

The first part of the workflow builds the site. 

If you like using a `Makefile` like me, you could use `make install` and `make build` as your steps.

Or be explicit with using `pip` or `mkdocs` for a Python project for example.

In my gist, I use a JavaScript app installed with `yarn`. Make sure to use the structure and indentation there, but here is a snippet.

```yaml
- name: Install 🔧
  run: yarn install

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

You could easily switch it to use `npm` instead. Both `npm` and `yarn` are available in the GitHub Actions environment _without_ additional actions loaded. If you need to do more advanced things like test multiple NodeJS versions, there are actions for that.


## Deploy step 🚀

The second part of the workflow targets a built folder and commits it to the `gh-pages` branch for GH Pages to use.

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

The `GITHUB_TOKEN` value will be filled in for you at build time - you can copy and paste the above code as is.

Configure `publish_dir` to be `public` or `build` for example.

If you are interested in the token types, see my [Token](https://github.com/MichaelCurrin/code-cookbook/tree/master/recipes/ci-cd/github-actions/tokens) guide.


## Other projects

I have a cookbook project where I collect patterns that work for me or that I find in other GitHub projects. See the section on [GitHub Actions](https://github.com/MichaelCurrin/code-cookbook/tree/master/recipes/ci-cd/github-actions). I provide many sample workflows there.


## Conclusion

Please let me know if you learnt something from this post or if you try out my workflow.

Here is a related post on the Hexo Quickstart project itself if you are interested:

- https://dev.to/michaelcurrin/hexo-quickstart-project-released-3f16