GitHub Pages
In this page:
git push origin branch_name
git checkout -b gh-pages
git push origin gh-pagesWhat is GitHub Pages
GitHub Pages is a free static-site host built directly into every GitHub repository -- push HTML, CSS, and JavaScript to a designated branch or folder, and GitHub serves it at a public URL with no separate hosting account or server to manage.
Example: What is GitHub Pages
git push origin main
# enable Pages in repository Settings, served at username.github.io/repoThe gh-pages Branch Convention
Many older projects and static-site generators publish to a dedicated gh-pages branch, kept separate from main so the built output never mixes with source code history -- tools like gh-pages (npm) or Jekyll automate pushing built files there.
Example: The gh-pages Branch Convention
git checkout -b gh-pages
git push origin gh-pagesActions-Based Deployment
Modern GitHub Pages setups typically use a GitHub Actions workflow that builds the site (e.g. running a static-site generator) and deploys the output automatically on every push to main, replacing the older manual gh-pages-branch workflow entirely.
Example: Actions-Based Deployment
# .github/workflows/deploy.yml
on:
push:
branches: [main]
jobs:
deploy:
steps:
- run: npm run buildCustom Domains
A GitHub Pages site can be served from your own domain instead of the default github.io URL by adding a CNAME file to the published branch and pointing your domain's DNS records at GitHub's servers.
Example: Custom Domains
echo "www.example.com" > CNAME
git add CNAME
git commit -m "Add custom domain"Troubleshooting a Pages Build
When a Pages deployment fails or shows a 404, the two most common causes are the wrong publish source selected in repository settings, or an index.html missing from the root of the published branch/folder -- checking the Actions tab's build log is usually the fastest way to diagnose it.
Example: Troubleshooting a Pages Build
ls index.html
# check Settings > Pages for the correct publish source- Publishing from the wrong branch or folder, so the site shows a 404; check the Pages source in the repository settings.
- Using absolute paths like
/style.cssin a project site, which breaks because it is served under/repo/. - Expecting Pages to run server code like PHP or Python, when it only serves static files.
- GitHub Actions and CI/CD pipelines automate building and testing code.
- Docker integration and deployment workflows help ship applications.
- GitHub Pages hosts static sites directly from a repository.
Chapter Quiz — Complete all 5 topics to unlock
0/5 topics done
Complete these topics first: