How to deploy Jekyll to GitHub Pages

In short

The settings

Pages source

GitHub Actions

Build

bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"

Folder it publishes

_site

Live at

USERNAME.github.io/REPO

Step by step

Set it up

1. 1

   Set the base path

   A GitHub Pages project site lives in a subfolder, USERNAME.github.io/REPO, so the build has to know that folder's name.

   Nothing to change: the workflow passes the right baseurl. In your templates, use {{ site.baseurl }} or the relative_url filter for links.

2. 2

   Add the workflow

   Create .github/workflows/deploy.yml in the repository with the file below. It builds the site on every push to main and publishes the result.

   name: Deploy to GitHub Pages
   
   on:
     push:
       branches: [main]
     workflow_dispatch:
   
   permissions:
     contents: read
     pages: write
     id-token: write
   
   concurrency:
     group: pages
     cancel-in-progress: false
   
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v7
         - uses: ruby/setup-ruby@v1
           with:
             ruby-version: "3.3"
             bundler-cache: true
         - id: pages
           uses: actions/configure-pages@v6
         - name: Build
           run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
           env:
             JEKYLL_ENV: production
         - uses: actions/upload-pages-artifact@v5
           with:
             path: _site
   
     deploy:
       needs: build
       runs-on: ubuntu-latest
       environment:
         name: github-pages
         url: ${{ steps.deployment.outputs.page_url }}
       steps:
         - id: deployment
           uses: actions/deploy-pages@v5
   

3. 3

   Switch Pages to GitHub Actions

   In the repository on GitHub, open the Pages settings and set the source to GitHub Actions. This is a one-time switch.

   Settings→Pages→Build and deployment→Source: GitHub Actions

4. 4

   Push, then open your site

   Commit and push to main. The Actions tab shows the build; when it turns green, the site is at https://USERNAME.github.io/REPO/. Every push after that deploys again.

Good to know

Common snags

• GitHub Pages can also build Jekyll itself, with Source set to Deploy from a branch and no workflow at all. That way only GitHub's approved plugins work; the workflow below runs any plugin in your Gemfile.
• Commit Gemfile.lock: the workflow installs exactly what's in it.

Questions

Before you start

Next step: connect your own domain to GitHub Pages.