Hosting static websites on GitHub pages
Tags: githubpages, githubactions, hosting
Published: 2023-02-03 09:39:28

---
title: Hosting static websites on GitHub pages
published: true
tags: ['githubpages', 'githubactions', 'hosting']
canonical_url: https://sevic.dev/github-pages-hosting-deployment/
---

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](https://pages.github.com/themes/) for GitHub pages. Specify the theme name in the `_config.yml` file.

```yml
# _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](https://www.namecheap.com/) website. Create a CNAME file with the domain name inside the repository.

```CNAME
sevic.dev
```

After purchasing the domain, go to Account &rarr; Dashboard &rarr; Manage &rarr; 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 &rarr; 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](https://sevic.dev/notes/github-actions-101/) when the changes are pushed to the specific branch. A GitHub token is required. Create it with `repo` permissions at [Tokens](https://github.com/settings/tokens) page. Set it as a GitHub action secret inside the project repository on Settings &rarr; Secrets and variables &rarr; Actions page.

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

```yml
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](https://sevic.dev/nextjs-deployment-vercel/) or [Netlify](https://sevic.dev/nextjs-deployment-netlify/).

### Boilerplate

Here is the [link](https://sevic.dev/nextjs-starter?ref=devto) to the boilerplate I use for the development.