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 currently enabled version at 3.9.0, you can use any version of Jekyll you want. For example 4.3.2, 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.

We’re only going to cover builds from the main branch in this page. Therefore, ensure that you are working on the main branch. If necessary, you may create it based on your default branch. When the Action builds your site, the contents of the destination directory will be automatically pushed to the gh-pages branch with a commit, ready to be used for serving.

The Action we’re using here will create (or reset an existing) gh-pages branch on every successful deploy.
So, if you have an existing gh-pages branch that is used to deploy your production build, ensure to make a backup of the contents into a different branch so that you can rollback easily if necessary.

The Jekyll site we’ll be using for the rest of this page initially consists of just a _config.yml, an 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 ''

gem 'jekyll', '~> 4.2'

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

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

GitHub Actions are registered for a repository by using a YAML file inside the directory path .github/workflows (note the dot at the start). For simplicity, here we use one of the Jekyll Actions to show you how to use the action.

Create a workflow file, say github-pages.yml, using either the GitHub interface or by pushing a YAML file to the workflow directory path manually. The base contents are:

name: Build and deploy Jekyll site to GitHub Pages

      - main # or master before October 2020

    runs-on: ubuntu-latest
      - uses: actions/[email protected]
      - uses: actions/[email protected]
          path: vendor/bundle
          key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile') }}
          restore-keys: |
            ${{ runner.os }}-gems-
      - uses: helaili/[email protected]    # Choose any one of the Jekyll Actions
        with:                                # Some relative inputs of your action
          token: ${{ secrets.GITHUB_TOKEN }}

The above workflow can be explained as the following:

  • We trigger the build using on.push condition for main branch only — this prevents the Action from overwriting the gh-pages branch on any feature branch pushes.
  • The name of the job matches our YAML filename: github-pages.
  • The checkout action takes care of cloning your repository.
  • The cache action is an optimization to avoid fetching and installing gems on every build.
  • We specify our selected action and version number using helaili/[email protected], this handles the build and deploy. You can choose any one of the Jekyll Actions that matches your project and flavor from GitHub Marketplace.
  • We set a reference to a secret environment variable for the action to use. The GITHUB_TOKEN is a secret token automatically initialized at the start of every workflow run. More information can be found in GitHub documentation.

Instead of using the on.push condition, you could trigger your build on a schedule by using the on.schedule parameter. For example, here we build daily at midnight by specifying cron syntax, which can be tested at the crontab guru site.

    - cron: "0 0 * * *"

Note that this string must be quoted to prevent the asterisks from being evaluated incorrectly.

Providing permissions

At the start of each workflow run, GitHub automatically creates a unique GITHUB_TOKEN secret to use in your workflow. You can use the GITHUB_TOKEN to authenticate in a workflow run. You can use the GITHUB_TOKEN by using the standard syntax for referencing secrets: $. For more information, please read GitHub’s docs on token authentication

If you need a token that requires permissions that aren’t available in the GITHUB_TOKEN, you can create a Personal Access Token (PAT), and set it as a secret in your repository for this action to push to the gh-pages branch:

  1. On your GitHub profile, under Developer Settings, go to the Personal Access Tokens section.
  2. Create a token. Give it a name like “GitHub Actions” and ensure it has permissions to public_repos (or the entire repo scope for private repository) — necessary for the action to commit to the gh-pages branch.
  3. Copy the token value.
  4. Go to your repository’s Settings and then the Secrets tab.
  5. Create a token named YOUR_CUSTOM_TOKEN (important). Give it a value using the value copied above.

Build and deploy

On pushing any local changes onto main, 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 now exist on the gh-pages branch.

On a successful build, GitHub Pages will publish the site stored on the repository gh-pages branches. Note that you do not need to setup a gh-pages branch or enable GitHub Pages, as the action will take care of this for you. (For private repositories, you’ll have to upgrade to a paid plan).

To see the live site:

  1. Go to the environment tab on your repository.
  2. Click View Deployment to see the deployed site URL.
  3. View your site at the URL. Make sure the timeago filter works as expected.
  4. Optionally add this URL to your repository’s main page and to your, to make it easy for people to find.

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

Be sure not to edit the gh-pages branch directly, as any changes will be lost on the next successful deploy from the Action.

  • jekyll-actions is an action available on the GitHub Marketplace and was used in this guide.
  • jekyll-actions-quickstart is an unofficial repository that includes a live demo of the jekyll-actions action. That project can be used as a template for making a new site.
  • jekyll-action-ts is another action to build and publish Jekyll sites on GiHub Pages that includes HTML formatting options with Prettier and caching.
  • jekyll-deploy-action is a GitHub Action to deploy the Jekyll site conveniently for GitHub Pages (An alternative action with better speed and compatibility).