Itanimulli

Setup GitHub Pages using Actions

GitHub recently changed how their Pages system works and many builders are broken without warning or much further information. To fix this you need to use their new actions and artifacts workflow.

Main Workflow

This file goes in .github/workflows/master.yml and is used to define two jobs: build and deploy. The build job builds the site using a static site generator and uploads an artifact, while the deploy job deploys the artifact to GitHub Pages. This example uses Zola as the static site generator. Every comment starting with NOTE may be customised to meet your needs, whether that is changing the static site generator, removing the ability to run manually, or allowing concurrent deployments to shadow each other.

name: Deploy Site to GitHub Pages

on:
  push:
    branches:
      - master

  # NOTE: allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# NOTE: allow only one concurrent deployment, skipping runs queued between the
# run in-progress and latest queued.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      ZOLA_VERSION: 0.18.0 # NOTE: specific to Zola
    steps:
      # NOTE: install your static site-generator to the image
      - name: Install Zola
        run: |
          set -x
          wget -O - \
             "https://github.com/getzola/zola/releases/download/v${ZOLA_VERSION}/zola-v${ZOLA_VERSION}-x86_64-unknown-linux-gnu.tar.gz" \
          | sudo tar xzf - -C /usr/local/bin

      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5

      # NOTE: static site builder which should output a directory including your
      # CNAME in the ./public directory
      - name: Build
        run: zola build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Deployment Script

I maintain a local history and push an orphaned commit of only the current state of the repository using the script below.

#!/bin/sh -e
git stash
git checkout --orphan tmp
git ls-files -z | xargs -0 git add # tracked files
git commit -m "init"
git push -f origin tmp:master
git checkout master
git branch -D tmp
git stash pop || true
#tutorial