Hosting static websites on GitHub pages

Published February 2, 2023Last updated March 22, 20233 min read

This post covers instructions for deploying to GitHub pages and domain setup.

GitHub Pages

GitHub provides a way to host a static website (e.g., Gatsby blog) for every repository on the gh-pages branch, which contains an index.html file. To make it work, create a public or private repository <GITHUB_USERNAME>.github.io. Every other repository will be available at the <GITHUB_USERNAME>.github.io/<REPOSITORY_NAME> URL.

GitHub Page themes

GitHub supports themes for GitHub pages. Specify the theme name in the _config.yml file.

# _config.yml
theme: jekyll-theme-midnight

Fill out the README.md file with some content.

Pushing the changes to the gh-pages branch will trigger the deployment pipeline.

DNS setup

A purchased domain is needed. You can buy it at Namecheap website. Create a CNAME file with the domain name inside the repository.


After purchasing the domain, go to Account Dashboard Manage Advanced DNS page on the Namecheap website. Create 4 A records with @ host to point to GitHub servers IP addresses (,, and and one CNAME record with www host and <GITHUB_USERNAME>.github.io value.

Enforce HTTPS connection on the Settings Pages page inside the GitHub repository.

Other public and private repositories will be available on the <DOMAIN>/<REPOSITORY_NAME> URL.

Continuous deployment

Deployment to GitHub pages can be automated with GitHub actions when the changes are pushed to the specific branch. A GitHub token is required. Create it with repo permissions at Tokens page. Set it as a GitHub action secret inside the project repository on Settings Secrets and variables Actions page.

Add the following configuration (which will build and deploy the project to the gh-pages branch) to .github/workflows/config.yml file.

name: Build and Deploy
- master
runs-on: ubuntu-latest
- name: Checkout 🛎️
uses: actions/checkout@v3
- name: Configure Node.js
uses: actions/setup-node@v3
node-version: 18
- name: Install and Build 🔧
run: |
npm ci
npm run build
- name: Deploy 🚀
uses: JamesIves/github-pages-deploy-action@v4
token: ${{ secrets.GH_TOKEN }}
BRANCH: gh-pages # The branch the action should deploy to
FOLDER: public # The folder the action should deploy
CLEAN: true # Automatically remove deleted files from the deploy branch


If you need to use sensitive environment variables, avoid committing them inside the repository and use an alternative for hosting, such as Vercel or Netlify.


© 2023