In the realm of static site generators, Jekyll stands tall as a popular choice among content creators and developers alike. Its simplicity and flexibility make it an ideal tool for crafting stunning websites and blogs (or not-so-stunning ones, like this one). If you’re using Jekyll to power your website and want to streamline the deployment process to GitHub Pages, you’re in the right place. In this post, we’ll guide you through the steps to publish your Jekyll site to a separate GitHub Pages repository using GitHub Actions.

Why Separate Repositories?

Before we dive into the technical details, you might wonder why you’d want to publish your Jekyll site to a different repository than to a gh-pages branch in your site’s source code.

Isolation: Keeping your source code and published site in separate repositories helps maintain a cleaner project structure. It reduces the clutter in your source repository and isolates your published site for easier management.

Security: By separating your source code from your published site, you minimize the risk of accidentally exposing sensitive information or configuration details in your public repository. Remember, your GitHub Pages site needs to be a public GitHub repository. You can, however, keep your Jekyll source files in a different, private repository.

Steps to Deploy Your Jekyll Site

Now, let’s get into the nitty-gritty of deploying your Jekyll site to a separate GitHub Pages repository using GitHub Actions. Here’s a step-by-step guide:

Step 1: Create a New Repository for Your GitHub Pages Site

Start by creating a new GitHub repository (typically called <your username>.github.io) dedicated to your GitHub Pages site. This will serve as the target repository where your Jekyll-generated HTML files will be deployed.

Step 2: Configure GitHub Actions Workflow

In your source code repository (the one containing your Jekyll project), you’ll need to set up a GitHub Actions workflow. Create a .github/workflows directory in your source code repository and add a YAML file (e.g., deploy.yml) to define your workflow.

Here’s an example workflow configuration:

name: Build and Publish Jekyll Site

on:
  push:
    branches:
      - master # Change this to your master branch's name

jobs:
  build:
    runs-on: ubuntu-latest
    steps:

      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Set Up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: 3.1.2 # Adjust as needed

      - name: Install Dependencies
        run: |
          gem install bundler
          bundle install
      
      - name: Build Jekyll Site
        run: |
          bundle exec jekyll build
     
      - name: Deploy Site
        uses: peaceiris/actions-gh-pages@v3
        with:
          external_repository: <your username>/<your github pages repo>
          deploy_key: ${{ secrets.DEPLOY_KEY }}
          publish_branch: master # Change this to your master branch's name
          publish_dir: ./_site # change to the output dir of your Jekyll build

This workflow checks out your source code, sets up the required Ruby environment, builds your Jekyll site, and deploys it to your GitHub Pages repository.

Step 3: Create and Use a Deploy Key

To securely deploy your site to the GitHub Pages repository, you can create and use a deploy key or a personal access token. The above example uses the property for a deploy key.

Here’s how to create and use a deploy key:

  • On your local machine, open a terminal.
  • Use the following command to generate an SSH key pair. Replace with a descriptive name for your key.
ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f <your key name> -N ""
  • You’ll get two files, one with a .pub extension (a public key) and one with no extension (a private key).
  • Go to your Github Pages repository and add the public key there and tick “Allow write access”
  • Go to the Secrets of your Jekyll source repository and add your private key as DEPLOY_KEY(or give it another name, but that needs to be reflected in the Action YAML.)

Note: Deploy keys are typically not protected by a passphrase for automation purposes, as they are used in automated workflows where manual intervention to enter a passphrase isn’t desired. However, it’s crucial to take steps to secure your deploy key by reducing the attack surface, which is easier to do if you’re the sole contributor to your repository and you’re pushing to your GitHub Pages site from one single location. And if you suspect any security breach, rotate the key.

Step 4: Commit and Push Changes

Commit the changes to your source code repository and push them to your master branch (or the branch you specified in the workflow configuration). This will trigger the GitHub Actions workflow.

If you want, you can go to the “Actions” tab in your source code repository on GitHub to monitor the progress of your workflow. Once it’s complete, your Jekyll site will be deployed to your GitHub Pages repository. You can monitor that workflow by going to your GitHub Pages repository and view the Actions there.

Step 5: Access Your Published Site

Visit https://<your GitHub username>.github.io/ in your web browser to access your published Jekyll site, where username is your GitHub username.

By following these steps, you’ve successfully set up an automated deployment pipeline for your Jekyll site to a separate GitHub Pages repository. This approach not only keeps your source code clean but also ensures that your website is always up-to-date with the latest changes, every time you push to GitHub.