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:

• Replace regular Jekyll gem with the github-pages gem in your Jekyll repository
• Enable GitHub pages on your repository via the project’s GitHub settings menu
• Push to the master branch of your GitHub repo

The Jekyll source code will be then be run on subsequent pushes to the master branch and automatically published to your site. Typically, this will then be available for viewing either at yourusername.github.io or yourusername.github.io/projectname depending on your setup.

If you’re interested in getting started quickly, this is a good approach to take and both the jekyllrb site and GitHub docs have good resources documenting the process.

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.

Specifically, this is because GitHub Pages only supports a small subset of available gems, and not always the latest versions of those gems. Further, if you need the most recent version of Jekyll, you’d be out of luck with GitHub Pages.

One potential fix for this is posting the actual site content to GitHub Pages rather than the Jekyll source code. The method for this is to basically run the Jekyll build on your local machine first, then check in the _site directory. This approach would require multiple repositories for your code or at least multiple branches since your source and you site would need to be versioned separately.

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.

To get this up and running, I recommend just following this guide from the jekyllrb site. I found it pretty straightforward and got it working after only a few minutes. However, there are a few changes that I would suggest after you get it working initially.

In case the linked Jekyll docs get updated, I am including a copy of their suggested github-pages.yml below as it is at the time of writing. If the docs get updated, the rest of this section may become irrelevant. Before getting started with the following changes, I'd also encourage you to replace the github-pages gem with the appropriately versioned jekyll gem as well.

jekyllrb github-pages.yml :

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 }}

The first change that I would suggest is updating to the latest version of the jekyll-action action in case there are any performance improvements or bug fixes. The latest releases can be found here. Currently, the latest version is 2.0.4 so the yml file becomes:

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 }}

When I made this change on my personal articles site, the build started to immediately fail with this error:

Could not locate Gemfile

This was pretty confusing since I had actually already committed my Gemfile. If you run into this issue, the fix is to also commit the Gemfile.lock file which I had previously had gitignored.

I would also recommend using the GitHub Actions cache since it will lead to faster build times for your builds. This is important since GitHub Actions keeps track of the amount of machine time that your actions use and the amount is limited based on the tier that you are using. At the time of writing this is 2000 minutes per month in the free plan and 3000 for the pro plan. More specifics can be found on the GitHub Actions site.

Before implementing caching, each of my builds was taking around 3 minutes since it had to create the container and then ensure all of the appropriate gems were installed. With caching enabled, builds came down to 1 minute so the time savings were noticeable for me. I think that for larger sites or those with many writers the time savings might be a smaller percentage of the total build time overall but I can’t say personally. Either way, saving time is important since the amount of minutes that are free is limited.

To add caching, we just update our action to use the cache as shown below.

Updated github-pages.yml :

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 }}

The above is actually the same for my personal site as well for the time being so I can at least guarantee that it works to some extent. Now, whenever I push to master, I can be sure that my site will build properly and push to my GitHub Pages site while also having the flexibility to use any additional Jekyll plugins that I want.

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.

Also, while we are using the helaili/jekyll-action, we aren’t using all of it’s features, so you should check out its Action Marketplace Page in case it has any other features that may be helpful to you. There are also Jekyll actions other than this specific one so there might be another one out there that fits your needs better, so take a look through the action library if this one doesn’t suit your needs exactly

I definitely recommend trying GitHub Actions for your own site, especially if you had been using GitHub pages in the first place and ever found yourself wanting to use unsupported plugins.

Originally published at https://jdvp.me on November 7, 2020.