github_pages.yml

---
name: 'GitHub pages deployment'
on:  # yamllint disable-line rule:truthy
  push:
    branches:
      - 'main'

    paths:
      - 'docs/**.md'
      - '.github/workflows/github_pages.yml'

  pull_request:
    branches:
      - 'main'

    paths:
      - 'docs/**.md'
      - '.github/workflows/github_pages.yml'

  workflow_dispatch: {}

permissions:
  contents: 'read'

concurrency:
  group: 'ci-${{ github.workflow }}-${{ github.ref }}'
  cancel-in-progress: false

env:
  # Jekyll image to use
  # yamllint disable rule:line-length
  # renovate image dep:
  jekyll-image: 'ghcr.io/sscheib/ansible-role-file_deployment-jekyll:v24.12.25@sha256:7d2e5a83fe7ef91e507b2b8a22c11ac719109bcea879fb675cfcd353efc81476'
  # yamllint enable rule:line-length

  # gitleaks image to use to check files prior to uploading them to prevent sensitive data being leaked
  # yamllint disable rule:line-length
  # renovate image dep:
  gitleaks-image: 'ghcr.io/gitleaks/gitleaks:v8.22.0@sha256:9c008fc701d3a0a2a15b77a7677b940e2e5942e8af8cc2a0b6e078c4365c3c86'
  # yamllint enable rule:line-length

jobs:
  build:
    name: 'Build documentation'
    runs-on: 'ubuntu-24.04'
    steps:
      - name: 'Harden Runner'
        uses: 'step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f' # v2.10.2
        with:
          egress-policy: 'block'
          allowed-endpoints: >
            api.github.com:443
            ghcr.io:443
            github.com:443
            pkg-containers.githubusercontent.com:443

      - name: 'Checkout the repository'
        uses: 'actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683' # v4.2.2

      - name: 'Build Jekyll site'
        shell: 'bash'
        run: |
          # fail if:
          # - a variable is unbound
          # - any command fails
          # - a command in a pipe fails
          # - a command in a sub-shell fails
          set -Eeuo pipefail

          # enable debug if runner runs in debug
          [[ "${{ runner.debug }}" -ne 1 ]] || {
            echo "INFO: Enabling bash trace";
            set -x;
          };

          # create _site directory with correct permissions
          mkdir "./docs/_site" && \
          sudo chown -R 1000:1000 "./docs/_site"

          # build documentation
          docker run --rm --volume "./docs:/srv/jekyll" "${{ env.jekyll-image }}" \
            bundler exec jekyll build --disable-disk-cache

      - name: 'Scan site directory to ensure it contains no secrets prior to uploading'
        shell: 'bash'
        run: |
          # fail if:
          # - a variable is unbound
          # - any command fails
          # - a command in a pipe fails
          # - a command in a sub-shell fails
          set -Eeuo pipefail

          # enable debug if runner runs in debug
          [[ "${{ runner.debug }}" -ne 1 ]] || {
            echo "INFO: Enabling bash trace";
            set -x;
          };

          docker run -v "./docs/_site:/scan" "${{ env.gitleaks-image }}" detect --source "/scan" --no-git || {
            echo "ERROR: Secret found, failing workflow";
            exit 1;
          };

      - name: 'Upload artifact to pass the build to the deploy job'
        if: "${{ github.event_name != 'pull_request' }}"
        uses: 'actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b' # v4.5.0
        with:
          name: 'jekyll-artifact'
          overwrite: true
          path: './docs/_site/'
          retention-days: 1

  deploy:
    name: 'Deploy documentation to GitHub Pages'
    if: "${{ github.event_name != 'pull_request' }}"
    needs: 'build'
    runs-on: 'ubuntu-24.04'
    permissions:
      id-token: 'write'
      pages: 'write'
    environment:
      name: 'github-pages'
      url: '${{ steps.pages-info.outputs.page_url }}'
    steps:
      - name: 'Harden Runner'
        uses: 'step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f' # v2.10.2
        with:
          egress-policy: 'block'
          allowed-endpoints: >
            api.github.com:443
            ghcr.io:443
            github.com:443
            pkg-containers.githubusercontent.com:443

      - name: 'Download build artifact'
        uses: 'actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16' # v4.1.8
        with:
          name: 'jekyll-artifact'
          path: './docs/_site/'

      - name: 'Gather information about the GitHub pages deployment'
        uses: 'actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b' # v5.0.0
        id: 'pages-info'
        with:
          token: '${{ secrets.GITHUB_TOKEN }}'
          enablement: false

      - name: 'Scan site directory to ensure it contains no secrets prior to uploading'
        shell: 'bash'
        run: |
          # fail if:
          # - a variable is unbound
          # - any command fails
          # - a command in a pipe fails
          # - a command in a sub-shell fails
          set -Eeuo pipefail

          # enable debug if runner runs in debug
          [[ "${{ runner.debug }}" -ne 1 ]] || {
            echo "INFO: Enabling bash trace";
            set -x;
          };

          docker run -v "./docs/_site:/scan" "${{ env.gitleaks-image }}" detect --source "/scan" --no-git || {
            echo "ERROR: Secret found, failing workflow";
            exit 1;
          };

      - name: 'Upload GitHub pages artifact'
        uses: 'actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa' # v3.0.1
        with:
          name: 'github-pages'
          path: './docs/_site'
          retention-days: 1

      - name: 'Deploy GitHub pages'
        uses: 'actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e' # v4.0.5
        with:
          token: '${{ secrets.GITHUB_TOKEN }}'
          artifact_name: 'github-pages'
...