GitHub Pages Skill

Complete guide for deploying, configuring, and managing GitHub Pages sites.

Quick Reference

Site Type Repository Name URL Pattern

User/Org Site <username>.github.io

https://<username>.github.io

Project Site Any repository name https://<username>.github.io/<repo>

Availability:

• Public repos: GitHub Free (all plans)

• Private repos: GitHub Pro, Team, Enterprise

Workflow Routing

When executing a workflow, output this notification directly:

Running the WorkflowName workflow from the GithubPages skill...

Workflow Trigger File

QuickStart "setup github pages", "create pages site" workflows/QuickStart.md

CustomDomain "add custom domain", "configure domain" workflows/CustomDomain.md

JekyllSetup "setup jekyll", "add jekyll theme" workflows/JekyllSetup.md

ActionsWorkflow "custom build", "github actions for pages" workflows/ActionsWorkflow.md

Troubleshoot "pages not working", "fix github pages" workflows/Troubleshoot.md

Deploy "deploy to github pages", "publish site" workflows/Deploy.md

Examples

Example 1: Create a new GitHub Pages site

User: "Setup GitHub Pages for my project" → Invokes QuickStart workflow → Checks if user/org or project site → Configures publishing source (branch or Actions) → Creates initial content structure → Verifies deployment

Example 2: Add custom domain

User: "Add my domain example.com to GitHub Pages" → Invokes CustomDomain workflow → Determines domain type (apex vs subdomain) → Provides DNS configuration instructions → Adds CNAME file or configures via Settings → Enables HTTPS enforcement

Example 3: Setup Jekyll theme

User: "Add a theme to my GitHub Pages site" → Invokes JekyllSetup workflow → Lists available supported themes → Configures _config.yml → Sets up custom CSS/layouts if needed

Example 4: Deploy with custom build

User: "Deploy my Next.js site to GitHub Pages" → Invokes ActionsWorkflow workflow → Creates custom GitHub Actions workflow → Configures build process → Sets up artifact deployment

Site Types

User/Organization Site

Requirements:

• Repository name MUST be <username>.github.io

• Only ONE per account

• Publishes from default branch

Setup:

Create repository named exactly: username.github.io

Enable Pages in Settings > Pages

Select source branch

Project Site

Requirements:

• Can use any repository

• Multiple project sites allowed

• URL includes repository name

Setup:

Any repository works

Enable Pages in Settings > Pages

Choose: branch (root or /docs) OR GitHub Actions

Publishing Sources

Option 1: Deploy from Branch

Best for: Jekyll sites, simple static sites

Configuration:

• Go to Settings > Pages

• Select "Deploy from a branch"

• Choose branch (main, gh-pages, etc.)

• Choose folder: / (root) or /docs

Behavior:

• Pushes to branch trigger automatic builds

• Jekyll processes Markdown by default

• CNAME file auto-created for custom domains

Option 2: GitHub Actions Workflow

Best for: Custom builds, non-Jekyll generators

Configuration:

• Go to Settings > Pages

• Select "GitHub Actions"

• Create workflow file in .github/workflows/

Behavior:

• Full control over build process

• Works with Hugo, Gatsby, Next.js, etc.

• Artifacts uploaded and deployed

Jekyll Integration

Auto-Enabled Plugins

These plugins work automatically on GitHub Pages:

Plugin Purpose

jekyll-coffeescript CoffeeScript support

jekyll-default-layout Automatic layouts

jekyll-gist GitHub Gist embedding

jekyll-github-metadata Repository metadata

jekyll-optional-front-matter Optional YAML front matter

jekyll-paginate Pagination

jekyll-readme-index README as index

jekyll-titles-from-headings Auto-generate titles

jekyll-relative-links Convert relative links

Supported Themes

Available without additional configuration:

• Architect

• Cayman

• Dinky

• Hacker

• Leap day

• Merlot

• Midnight

• Minima

• Minimal

• Modernist

• Slate

• Tactile

• Time machine

Usage in _config.yml :

theme: jekyll-theme-minimal title: My Site description: Site description

Remote Themes

Use any Jekyll theme from GitHub:

remote_theme: owner/repo-name

Custom Domains

Domain Types

Type Example DNS Record

Apex example.com

A or ALIAS

WWW Subdomain www.example.com

CNAME

Custom Subdomain blog.example.com

CNAME

DNS Configuration

For Apex Domains (A Records):

185.199.108.153 185.199.109.153 185.199.110.153 185.199.111.153

For Apex Domains (AAAA Records - IPv6):

2606:50c0:8000::153 2606:50c0:8001::153 2606:50c0:8002::153 2606:50c0:8003::153

For Subdomains (CNAME Record):

www.example.com → username.github.io blog.example.com → username.github.io

Verification Commands

Check A records

dig example.com +noall +answer -t A

Check AAAA records

dig example.com +noall +answer -t AAAA

Check CNAME records

dig www.example.com +nostats +nocomments +nocmd

Usage Limits

Resource Limit

Repository size 1 GB (recommended)

Published site size 1 GB (maximum)

Bandwidth 100 GB/month (soft)

Builds 10/hour (soft, branch only)

Deployment timeout 10 minutes

Restrictions:

• No server-side languages (PHP, Python, Ruby)

• No commercial transactions or e-commerce

• Must comply with GitHub Terms of Service

Security Best Practices

• Verify custom domains - Prevents domain takeover attacks

• Avoid wildcard DNS - *.example.com creates security risks

• Enable HTTPS - Always enforce HTTPS after certificate provisioning

• Don't expose secrets - Public sites accessible even from private repos

• Update DNS promptly - If disabling site, update/remove DNS records

Common Issues & Solutions

Issue Solution

Site not publishing Check branch/folder settings, verify entry file exists

404 errors Ensure index.html , index.md , or README.md at root

Custom domain not working Wait 24h for DNS propagation, verify records with dig

HTTPS not available Wait up to 1 hour after DNS verification

Mixed content warnings Change http:// to https:// in all assets

Build failures Check Actions tab for error logs

File References

Topic Reference File

DNS Configuration references/DnsConfiguration.md

Jekyll Configuration references/JekyllConfiguration.md

Actions Workflows references/ActionsWorkflows.md

Troubleshooting Guide references/Troubleshooting.md

Best Practices references/BestPractices.md

Scripts

Script Purpose

scripts/verify-dns.sh

Verify DNS configuration for custom domains

scripts/check-site-status.sh

Check if GitHub Pages site is live

External Documentation

• GitHub Pages Quickstart

• Custom Domain Configuration

• Jekyll Documentation

• GitHub Actions for Pages