What is Jekyll, GitHub, and Cloudflare Pages?

Jekyll is a static site generator that transforms plain text into beautiful websites without a database. GitHub provides version control and private repository hosting for your project code. Cloudflare Pages is a lightning-fast JAMstack platform that automatically deploys your site whenever you push changes. Together, they create a secure, scalable, and maintenance-free publishing workflow perfect for developers who want full control over their web presence.

---

Part 1: Local Jekyll Setup (If You Haven't Already)

Prerequisites

Step 1: Install Ruby (if needed)

On macOS:

brew install rbenv
rbenv init
# Close and reopen terminal
rbenv install 3.2.2
rbenv global 3.2.2
ruby --version

On Windows: Download and install from https://www.ruby-lang.org/en/downloads/

On Linux:

sudo apt-get install ruby-full build-essential zlib1g-dev
ruby --version

Step 2: Install Jekyll and Bundler

gem install jekyll bundler

Step 3: Create Your Jekyll Site (or use existing)

If you already have a Jekyll site, skip to Part 2. If creating new:

jekyll new my-jekyll-site
cd my-jekyll-site

Step 4: Ensure Gemfile is Configured

Your Gemfile should look like this:

source "https://rubygems.org"
gem "jekyll", "~> 4.3.0"
gem "minima", "~> 2.5"

group :jekyll_plugins do
gem "jekyll-feed", "~> 0.12"
gem "jekyll-seo-tag", "~> 2.8"
end

platforms :mingw, :x64_mingw, :mswin, :jemalloc do
gem "tzinfo", ">= 1", "< 3"
gem "tzinfo-data"
end

gem "wdm", "~> 0.1.1", platforms: [:mingw, :x64_mingw, :mswin]

Step 5: Test Locally

cd my-jekyll-site
bundle install
bundle exec jekyll serve

Visit http://localhost:4000 to verify everything works. Press Ctrl+C to stop the server.

---

Part 2: Create Gemfile.lock

This file is crucial for Cloudflare to build your site with the exact same dependencies.

cd /path/to/your/jekyll/site
bundle lock

This creates a Gemfile.lock file. Commit this to GitHub—Cloudflare needs it.

---

Part 3: Create GitHub Personal Access Token

You need a token to push code to GitHub from your PC.

---

Part 4: Create Private GitHub Repository

Step 1: Create the Repo

Step 2: You'll See Instructions

GitHub will show you a page with commands. We'll use these in the next step.

---

Part 5: Push Your Jekyll Site to GitHub

Step 1: Navigate to Your Jekyll Site Directory

cd /path/to/your/jekyll/site

Step 2: Initialize Git and Push

Run these commands in order (replace YOUR_USERNAME with your GitHub username):

git init
git add .
git commit -m "Initial Jekyll site commit"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/my-jekyll-site.git
git push -u origin main

Step 3: Authenticate with GitHub

When prompted for a password, paste your Personal Access Token (not your GitHub password).

Example interaction:

Username for 'https://github.com': YOUR_USERNAME
Password for 'https://YOUR_USERNAME@github.com': [paste your token here]

Step 4: Verify Upload

---

Part 6: Create Cloudflare Account & Connect Domain

Step 1: Create Cloudflare Account

Step 2: Add Your Domain (or use free .pages.dev domain)

Option A: Use the Default Pages Domain ➜ Skip to Part 7

• Your site will be at your-site.pages.dev

Option B: Add Your Own Domain

---

Part 7: Connect GitHub to Cloudflare Pages

Step 1: Access Cloudflare Pages

Step 2: Authorize GitHub

Step 3: Select Repository

Step 4: Configure Build Settings

You'll see a form with these fields. Fill them in exactly:

Step 5: Set Environment Variables

Click Environment variables to expand it.

Add one variable:

Click Save to add the variable.

Step 6: Deploy

Step 7: Test Your Site

Click the URL provided. Your Jekyll site shoold be live!

---

Part 8: Connect Custom Domain (Optional)

If you added your own domain in Part 6:

Part 9: Enterprise-Grade Security Configuration

Step 1: Enable HTTPS Everywhere

Step 2: Web Application Firewall (WAF)

Step 3: DDoS Protection

Step 4: Bot Management

Step 5: Security Headers

Create rules to add these headers:

Rule 1:

• Name: Add X-Content-Type-Options
• When incoming requests match: (leave as "All incoming requests")
• Header: X-Content-Type-Options
• Value: nosniff
• Click Deploy

Rule 2:

• Name: Add X-Frame-Options
• Header: X-Frame-Options
• Value: DENY
• Click Deploy

Rule 3:

• Name: Add X-XSS-Protection
• Header: X-XSS-Protection
• Value: 1; mode=block
• Click Deploy

Rule 4:

• Name: Add Referrer-Policy
• Header: Referrer-Policy
• Value: strict-origin-when-cross-origin
• Click Deploy

Step 6: Content Security Policy (Optional but Recommended)

1. In Transform Rules → Modify Response Header
2. Click Create rule

Rule:

• Name: Add Content-Security-Policy
• Header: Content-Security-Policy
• Value: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:
• Click Deploy

Step 7: Caching for Performance

Rule for Static Assets:

Rule for HTML:

• When incoming requests match: (cf.mime_type eq "text/html")
• Then: Set cache TTL to 1 hour
• Click Deploy

Step 8: Enable Compression & Minification

---

Part 10: Making Changes to Your Site

From now on, your workflow is super simple:

To Update Your Site:

bundle exec jekyll serve

git add .
git commit -m "Updated homepage"
git push origin main

You never have to touch Cloudflare's dashboard again unless you want to tweak security settings.

---

Part 11: Troubleshooting

Build fails with "Gemfile not found"

• Make sure you committed Gemfile and Gemfile.lock to GitHub
• Push them again if missing: git add Gemfile Gemfile.lock && git commit -m "Add Gemfiles" && git push

Build fails with Ruby version error

• Check your local Ruby version: ruby --version
• Update the RUBY_VERSION environment variable in Cloudflare Pages to match

Site looks broken (missing CSS/images)

• Clear your browser cache (Ctrl+Shift+Delete or Cmd+Shift+Delete)
• Wait a few minutes for cache to propagate
• Check that file paths in Jekyll are correct

GitHub authentication keeps failing

• Make sure you're using your Personal Access Token, not your password
• Regenerate a new token if the old one expires

Cloudflare won't connect to GitHub repo

• Make sure your GitHub repo is set to Private
• Re-authorize Cloudflare in your GitHub settings

Site is slow

• Check your Cloudflare caching rules are enabled
• Verify minification is turned on in Speed → Optimization
• Use Cloudflare's Speed Insights tool to diagnose

---

Security Checklist

Before going live, verify:

---

Useful Commands Reference

Check Ruby version:

ruby --version

Check if Git is installed:

git --version

View Git remote:

git remote -v

Check Git status:

git status

View local commits:

git log --oneline

Push to GitHub:

git push origin main

Pull from GitHub:

git pull origin main

Create a new branch (for experiments):

git checkout -b my-feature-branch
git push origin my-feature-branch

---

Resources

• https://jekyllrb.com/docs/
• https://developers.cloudflare.com/pages/
• https://docs.github.com/

---