Building site based on Jekyll 4.2 using GitHub Actions

Today I decided to check feature GitHub Actions. My goal is to prepare configuration for GitHub Actions and publish a site based on Jekyll 4.2

GitHub Pages uses Jekyll 3.9

I’m adding this part because I forgot the reasons for my decision. I maintain several Jekyll-based websites / blogs. It’s time to update Ruby on one of the blogs. Edit .ruby-version file, then run bundle install. And finally, run jekyll server: jekyll s. It’s failed, a message popped up:

jekyll 3.9.0 | Error:  no implicit conversion of Hash into Integer
/home/torrocus/.rvm/gems/ruby-3.0.0@blog/gems/pathutil-0.16.2/lib/pathutil.rb:502:in `read': no implicit conversion of Hash into Integer (TypeError)

Googling the phrase “jekyll 3.9.0 | Error: no implicit conversion of Hash into Integer” leads me to a simple conclusion: Jekyll 3.9 is not compatible with Ruby 3.

The solution is to update Jekyll to at least 4.x. However, here comes another problem. GitHub Pages doesn’t support Jekyll 4.x. Current supported versions can be found on the GitHub official dependency page.

In short, as long as GitHub Pages is using Jekyll 3.9, neither Jekyll nor Ruby will be able to be updated. The solution to this problem is to use GitHub Actions with Jekyll 4 or later.

GitHub Actions step by step for Jekyll

To use GitHub Actions, you need to create the folder .github/workflows. Inside this folder will be the GitHub Actions configuration. Each file is responsible for a separate GitHub Actions workflow. There are already actions at GitHub that help build a website based on Jekyll.

For the Jekyll build to go correctly, you need a JEKYLL_PAT key. To generate the key go to Settings in your GitHub profile. Then go to Developer settings and then go to Personal access tokens. Click Generate new token button and confirm your GitHub password. Fill out the form New personal access token as follows:

Note: GitHub Actions
Select checkbox public_repo
Click Generate token

A new GitHub API key will appear, so copy it. You have to paste it elsewhere, so if you lose it, you have to repeat the process.

Now go to the repository Settings and go to the Secrets settings. Click the New secret button and fill in the Secrets / New secret form as below:

Name: JEKYLL_PAT
Value: paste the copied GitHub Actions key here
Click Add secret

Settings on the GitHub side are almost ready. Now you need to prepare the configuration on the repository side.

Configuration file .github/workflows/deployment.yml:

name: deployment

on:
  push:
    branches:
      - master

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

    - 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.3
      env:
        JEKYLL_PAT: ${{ secrets.JEKYLL_PAT }}

After doing git commit and git push, the GitHub Actions process should start. The process workflow can be viewed in the tab Actions. The name of this process is deployment (see the value of the key name in .github/workflows/deployment.yml file). After selecting the process name (in this case deployment) and commit name, you can see the GitHub Action process workflow.

▶ ✓ Set up job
▶ ✓ Build helaili/jekyll-action@2.0.3
▶ ✓ Run actions/checkout@v2
▶ ✓ Run actions/cache@v1
▶ ✓ Run helaili/jekyll-action@2.0.3
▶ ✓ Post Run actions/cache@v1
▶ ✓ Post Run actions/checkout@v2
▶ ✓ Complete job

If everything is green, it means that the whole process was successful. If any step fails, you need to read the detailed information for that step. A good practice is to add a badge to the README file.

![Build and deploy](https://github.com/USER/REPO/workflows/WORKFLOW/badge.svg)

Where USER is the username, REPO is the GitHub repository name and WORKFLOW is the name of the GitHub Action process. Below is a preview of passing and failing badges.

In most cases, the above instructions should allow you to build static websites based on Jekyll on GitHub Actions. This blog also uses this configuration.

Possible problems

There have been various problems recently.

Could not read Password

Your Jekyll site is working locally. You used GitHub Actions to build it, but finally got this message:

fatal: could not read Password for 'https://***@github.com': No such device or address

This means that you need to reset the GitHub Actions token.

Simple dictionary

JEKYLL_PAT - Jekyll Personal Access Token