Automating Jekyll Deployment to GitHub Pages with GitHub Actions

This guide shows how to build and deploy a Jekyll site to GitHub Pages using GitHub Actions. GitHub Pages will serve your site directly from the artifact built in the workflow.

Overview
Requirements
Repository Setup
Jekyll Site Structure
Creating the Deployment Workflow
Configuring GitHub Pages
Deploying the Site
Troubleshooting

1. Overview

We’ll use a GitHub Actions workflow to:

Build your Jekyll site from source
Package the static output from _site/ into a Pages artifact
Deploy to GitHub Pages using that artifact

2. Requirements

You need:

A GitHub repository (public or private)
A valid Jekyll site with:
- _config.yml
- Gemfile
A default branch named main
GitHub Pages source set to GitHub Actions

3. Repository Setup

Your project should include the following files:

.
├── _config.yml
├── index.md
├── _posts/
├── _layouts/
├── Gemfile
├── Gemfile.lock
└── .github/
    └── workflows/
        └── gh-pages.yml

Ensure Gemfile includes at minimum:

source "https://rubygems.org"
gem "jekyll"

Run locally:

bundle install

Commit both Gemfile and Gemfile.lock.

4. Jekyll Site Structure

Make sure your Jekyll site has a valid _config.yml. Example:

title: My Site
baseurl: "" # Leave empty for apex or user site
url: "https://username.github.io" # or your custom domain

You can test locally with:

bundle exec jekyll serve

5. Creating the Deployment Workflow

Create the file .github/workflows/gh-pages.yml with the following contents:

name: GitHub Pages

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: write
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: $

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up Ruby
      uses: ruby/setup-ruby@v1
      with:
        ruby-version: '3.1.6'
        bundler-cache: true

    - name: Install dependencies
      run: |
        gem install bundler
        bundle install --without debug

    - name: Build Jekyll site
      run: |
        bundle exec jekyll build

    - name: Setup GitHub Pages
      uses: actions/configure-pages@v4

    - name: Upload artifact for GitHub Pages
      uses: actions/upload-pages-artifact@v3
      with:
        path: ./_site

    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4

6. Configuring GitHub Pages

To enable deployment from GitHub Actions:

Go to your repository → Settings
Click Pages in the sidebar
Under Build and deployment, set:
- Source: GitHub Actions

You do not need to choose a branch or folder. The workflow handles it.

7. Deploying the Site

Once the gh-pages.yml workflow is committed and pushed:

git add .
git commit -m "Set up automated Jekyll deployment"
git push origin main

Go to the Actions tab and watch the GitHub Pages workflow run. Once it finishes, your site will be live at:

User site: https://username.github.io
Project site: https://username.github.io/repo-name
Custom domain: https://yourdomain.com (if configured)

8. Troubleshooting

My site doesn’t deploy

Ensure bundle exec jekyll build succeeds locally
Confirm Gemfile includes jekyll
Make sure the Pages source is set to GitHub Actions

No HTTPS?

Make sure your domain is verified and configured correctly
Check Settings → Pages and ensure Enforce HTTPS is enabled

Caching or dependency issues?

Delete your vendor/ folder and try:

bundle update