GitHub Actions

When building a Jekyll site with GitHub Pages, the standard flow is restricted for security reasons and to make it simpler to get a site setup. For more control over the build and still host the site with GitHub Pages you can use GitHub Actions.

Advantages of using Actions

Control over gemset

  • Jekyll version — Instead of using the classic GitHub Pages provided version at 3.9.3, you can use any version of Jekyll you want. For example 4.3.3, or point directly to the repository.
  • Plugins — You can use any Jekyll plugins irrespective of them being on the supported versions list, even *.rb files placed in the _plugins directory of your site.
  • Themes — While using a custom theme is possible without Actions, it is now simpler.

Workflow Management

  • Customization — By creating a workflow file to run Actions, you can specify custom build steps, use environment variables.
  • Logging — The build log is visible and can be tweaked to be verbose, so it is much easier to debug errors using Actions.

Workspace setup

The first and foremost requirement is a Jekyll project hosted at GitHub. Choose an existing Jekyll project or follow the quickstart and push the repository to GitHub if it is not hosted there already.

The Jekyll site we’ll be using for the rest of this page initially consists of just a _config.yml, an index.md page and a Gemfile. The contents are respectively:

# _config.yml

title: "Jekyll Actions Demo"

---
---

Welcome to My Home Page

{% assign date = '2020-04-13T10:20:00Z' %}

- Original date - {{ date }}
- With timeago filter - {{ date | timeago }}

# Gemfile

source 'https://rubygems.org'

gem "jekyll", "~> 4.2"

group :jekyll_plugins do
  gem "jekyll-timeago", "~> 0.13.1"
end

The demo site uses Jekyll 4 and a third-party plugin, both of which are currently not whitelisted for use on GitHub pages. The plugin will allow us to describe how far back a date was from today. e.g. If we give a date as 2016-03-23T10:20:00Z and the current date is 2020-04-13T10:20:00Z, then the output would be 4 years and 3 weeks ago.

The action we’re using takes care of installing the Ruby gems and dependencies. While that keeps the setup simple for the user, one may encounter issues if they also check-in Gemfile.lock if it was generated with an old version of Bundler.

Setting up the Action

  1. Go to the Settings tab on your repository.
    1. Click Pages under Code and automation.
    2. Change Source under Build and deployment from Deploy from a branch to GitHub Actions.
  2. Go to the Actions tab on your repository.
    1. Start a New workflow and search for Jekyll.
    2. Click Configure under the Jekyll workflow (not GitHub Pages Jekyll workflow).
    3. Review the change and click Commit changes.

Build and deploy

On pushing any local changes onto the default branch, the action will be triggered and the build will start.

To watch the progress and see any build errors, check on the build status using one of the following approaches:

  • View by commit
    • Go to the repository level view in GitHub. Under the most recent commit (near the top) you’ll see a status symbol next to the commit message as a tick or X. Hover over it and click the details link.
  • Actions tab
    • Go to the repository’s Actions tab. Click on the jekyll workflow tab.

If all goes well, all steps will be green and the built assets will be uploaded to GitHub Pages.

To see the live site, go to the Deployments tab on your repository, and click on the deployed site URL.

When you need to make further changes to the site, commit to the default branch and push. The workflow will build and deploy your site again.

  • starter-workflows is the official repository providing the workflow template used in this guide.