Deploy Jekyll to GitHub Pages in 10 Minutes

GitHub Pages is the fastest way to get a Jekyll site online — and it’s completely free. This guide gets you from zero to a live site in 10 minutes.

What You Need

A GitHub account (free at github.com)
Git installed on your computer
Jekyll installed locally (optional, but useful for testing)

Option A: Deploy in 3 Minutes (Theme Chooser — No Local Setup)

If you just want something live quickly:

Create a new GitHub repository named username.github.io (replace username with your actual GitHub username)
Go to Settings → Pages
Under Source, select Deploy from a branch
Select the main branch and click Save
Go to Settings → Pages → Choose a theme to pick a basic theme

Your site is live at https://username.github.io within 2 minutes.

Limitation: The theme chooser only offers 12 basic GitHub-provided themes. For a real site, use Option B.

Option B: Deploy a Full Jekyll Site (Recommended)

Step 1: Create Your Jekyll Site Locally

gem install bundler jekyll
jekyll new my-site
cd my-site
bundle exec jekyll serve

Open http://localhost:4000 to see your site. Once happy with it, move to the next step.

Step 2: Create a GitHub Repository

Create a new repository on GitHub. For a personal/organisation site, name it username.github.io. For a project site, any name works.

Do not initialise the repository with a README — you’ll push from your local machine.

Step 3: Push to GitHub

In your local site directory:

git init
git add .
git commit -m "Initial Jekyll site"
git remote add origin https://github.com/username/repo-name.git
git push -u origin main

Step 4: Enable GitHub Pages

In your repository on GitHub:

Go to Settings → Pages
Under Source, select GitHub Actions
GitHub will detect your Jekyll site and suggest the Jekyll workflow — click Configure
Review the workflow file (the defaults work perfectly for most sites)
Click Commit changes

GitHub Actions will run your build and deploy automatically. Check the Actions tab to watch the build. In 1–2 minutes, your site is live.

Understanding GitHub Pages Site Types

Type	Repository Name	Live URL
User site	`username.github.io`	`https://username.github.io`
Organisation site	`orgname.github.io`	`https://orgname.github.io`
Project site	Any name	`https://username.github.io/repo-name`

For a project site, you need to set baseurl in _config.yml:

baseurl: "/repo-name"
url: "https://username.github.io"

For a user or organisation site, leave baseurl empty:

baseurl: ""
url: "https://username.github.io"

Setting Up a Custom Domain

To use yourdomain.com instead of username.github.io:

Step 1: In your repository, create a file called CNAME in the root with your domain:

yourdomain.com

Step 2: In your domain registrar’s DNS settings, add:

An A record pointing to GitHub’s IP addresses:
- 185.199.108.153
- 185.199.109.153
- 185.199.110.153
- 185.199.111.153
A CNAME record: www pointing to username.github.io

Step 3: In GitHub repository Settings → Pages, enter your custom domain and check Enforce HTTPS.

DNS changes take 5 minutes to 48 hours to propagate. Once they do, your site is live at your custom domain with a free SSL certificate.

The GitHub Actions Workflow Explained

When you choose the GitHub Actions source, GitHub creates a .github/workflows/jekyll.yml file like this:

name: Deploy Jekyll to GitHub Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Build with Jekyll
        uses: actions/jekyll-build-pages@v1
        with:
          source: ./
          destination: ./_site
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Every push to main triggers a build and deploy. You never have to run anything manually.

Troubleshooting Common Deployment Issues

Build fails with “Could not find gem” Your Gemfile.lock references a gem version not available in the GitHub Actions environment. Run bundle update locally and push the updated Gemfile.lock.

CSS/JS not loading on live site Check your baseurl setting in _config.yml. If you have a project site at username.github.io/repo, your baseurl must be /repo.

Site shows README instead of Jekyll site You are deploying from a branch, not via GitHub Actions. Go to Settings → Pages and switch the source to GitHub Actions.

Custom domain not working DNS propagation can take up to 48 hours. Check propagation at dnschecker.org. Make sure the CNAME file exists in your repo root.

Keeping Your Site Updated

Every time you push a commit to main, GitHub Actions rebuilds and deploys your site. The typical cycle:

Edit files locally
Test with bundle exec jekyll serve
Commit and push
GitHub deploys automatically in ~60 seconds

That’s it. No FTP, no SSH, no server management.

Looking for a great theme to deploy? Browse Jekyll themes on JekyllHub →

deploy jekyll github pages jekyll github pages github pages tutorial jekyll hosting