Hosting static websites on GitHub pages

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.

sevic.dev

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 (185.199.108.153, 185.199.109.153, 185.199.110.153 and 185.199.111.153) 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
on:
  push:
    branches:
      - master
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v4
      - name: Configure Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Install and Build 🔧
        run: |
          npm ci
          npm run build
      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          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

Notes

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.

Boilerplate

Here is the link to the boilerplate I use for the development.