Jekyll & GitHub Actions

The standard GitHub Pages process imposes limitations on which Jekyll plugins we can use. Let’s avoid this issue using GitHub Actions instead.

GitHub Pages

For the most part and in most simple cases, the basic Jekyll deployment flow on GitHub Pages is straight-forward and you can be up-and-running in a few minutes. The basic flow of deploying on GitHub pages in simple cases is as follows:

  • Enable GitHub pages on your repository via the project’s GitHub settings menu
  • Push to the master branch of your GitHub repo

Limitations

I was recently trying to add a tagging system to my Jekyll site (this page included!) and found that the AutoPages feature from the jekyll-paginate-v2 gem seemed like it would be perfect for the job. However, at the very top of the project’s README, it warns that it will not work with GitHub Pages.

Jekyll Paginate v2 Warns that it is not compatible with GitHub pages
Jekyll Paginate v2 Warns that it is not compatible with GitHub pages

Enter GitHub Actions

Although it isn’t exactly new, GitHub Actions is newer than GitHub pages. With actions, you can run automated tasks on your repositories for a variety of different scenarios. For example, you may want to run commit validation that must pass before Pull Requests can be merged. In our case, on every commit to the master branch, we want to run an action that will trigger a Jekyll build. Using this Actions-based approach, we can implement the 2-branch pattern we would manually have to do regularly.

name: Build and deploy Jekyll site to GitHub Pages

on:
push:
branches:
- master

jobs:
github-pages:
runs-on: ubuntu-16.04
steps:
- uses: actions/checkout@v2
- uses: helaili/jekyll-action@2.0.1
env:
JEKYLL_PAT: ${{ secrets.JEKYLL_PAT }}
name: Build and deploy Jekyll site to GitHub Pages

on:
push:
branches:
- master

jobs:
github-pages:
runs-on: ubuntu-16.04
steps:
- uses: actions/checkout@v2
- uses: helaili/jekyll-action@2.0.4
env:
JEKYLL_PAT: ${{ secrets.JEKYLL_PAT }}
Could not locate Gemfile
name: Build and deploy Jekyll site to GitHub Pages

on:
push:
branches:
- master

jobs:
github-pages:
runs-on: ubuntu-16.04
steps:
- uses: actions/checkout@v2

# Use GitHub Actions' cache to shorten build times and decrease load on servers
- uses: actions/cache@v1
with:
path: vendor/bundle
key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
restore-keys: |
${{ runner.os }}-gems-

- uses: helaili/jekyll-action@2.0.4
env:
JEKYLL_PAT: ${{ secrets.JEKYLL_PAT }}

Conclusion and Further considerations

Using GitHub Actions to deploy our Jekyll site can allow us to do use more advanced features since we aren’t limited to a subset of specific plugins that we can use. Although the setup is a bit more involved that the regular GitHub Pages setup, I believe the trade-off is worth it since the setup is a one-time investment. From an actual cost perspective, GitHub Actions for building a Jekyll site should likely be free unless you are using hundreds of builds a month and have builds that last many minutes each.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store