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?
- 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 post. 👩🏫
My workflow 📃
Today I setup a JavaScript-based Hexo site for the first time. I added a CI flow using GitHub 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.
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.
- 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.
- 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 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. 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:
Top comments (0)