Deploying Jekyll [v4] sites to GitHub Pages using GitHub Actions

The GitHub Pages (github-pages gem) only supports specific versions of Jekyll and Jekyll plugins. Latest version of Jekyll v4.x.x build time for your site is incredibly faster than older versions. So, to overcome the GitHub Pages dependencies and versions we are going to use GitHub Actions to deploy your site onto GitHub Pages with your specific version of Jekyll and Jekyll plugins.

Also, using GitHub Actions we 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.

Note: This is the updated post directly from Jekyll documentations site with much simpler procedures.

Workspace setup

The first and foremost requirement is a Jekyll project hosted at GitHub. Choose an existing Jekyll project or follow the quick start 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.

Warning: 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.

Following is the contents of Gemfile for our project:

# frozen_string_literal: true

source 'https://rubygems.org'

gem 'jekyll', '~> 4.2'

group :jekyll_plugins do
  gem 'jekyll-seo-tag', '~> 2.7', '>= 2.7.1'
  gem 'jekyll-sitemap', '~> 1.4'
end

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). Here we shall employ Jekyll Actions from the Marketplace for its simplicity.

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

name: deploy

on:
  push:
    branches:
      - main
    paths-ignore:
      - "README.md"
      - "LICENSE"

jobs:
  deploy:
    name: github-pages
    runs-on: ubuntu-latest

    steps:
      - name: Clone repository
        uses: actions/[email protected]

      - name: Caching for Bundler
        uses: actions/[email protected]
        with:
          path: vendor/bundle
          key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile') }}
          restore-keys: |
            ${{ runner.os }}-gems-

      - name: Build and deploy
        uses: helaili/[email protected]
        with:
          token: ${{ secrets.JEKYLL_PAT }}

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.
  • We specify our selected action and version number using helaili/[email protected]. This handles the build and deploy.
  • We set a reference to a secret token for the action to use. The JEKYLL_PAT is a Personal Access Token and is detailed in the next section.

Providing permissions

The action needs permissions to push to your gh-pages branch. So you need to create a GitHub authentication token on your GitHub profile, then set it as an environment variable in your build using Secrets:

  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 JEKYLL_PAT (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 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.

When you need to make further changes to the site, commit to main 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.

Further resources

Jekyll official documentations:

Popular ‘Jekyll build & deploy to GitHub Pages’ Actions on the GitHub Marketplace:

Popular ‘deploy to GitHub Pages’ Actions on the GitHub Marketplace: