Publishing and building a static website on GitHub Pages

A week ago or so I finally launched a small website I’ve been working on for quite some time: kevin.gimbel.dev/ops – it’s a colourful static website showing some of the technologies I’ve worked with in the past years since I began doing DevOps full time.

The website is built with 11ty and published with GitHub Pages.

Overview

Here’s what we do:

1. Build the code using 11ty
2. Publish the generated site to a gh-pages branch

To do this we need to first set our GitHub repository to deploy from a GitHub action. This is a new feature and currently in Beta.

With this setting enabled our GitHub action is used to deploy the static site.

The building is then done in a GitHub action. Here’s the code

name: Build eleventy site

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18

      - run: npm ci

      - run: npm run build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        if: ${{ github.ref == 'refs/heads/main' }}
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

With this config we do the following:

1. Checkout the code using the standard actions/checkout@v3 action from GitHub
2. Setup NodeJS with the actions/setup-node@v3 action, we specify 18 as version
3. Run npm ci to install dependencies
4. Run npm run build to execute the build script defined in the package.json
5. And finally we use peaceiris/actions-gh-pages@v3 to deploy the compiled code to the gh-pages branch.

This action works like a charm and builds the site in no time! Previously I had build the static site on my machine and setup GitHub pages to serve files from the docs folder. This works as well, but I didn’t want to run the compile commands by hand all the time.

By default all GitHub Pages run through Jekyll, which was also a waste of resources because this step did nothing. By providing my own build script that actually does something the default Jekyll one stopped running as well.