gh-pages.yml

---
# Front-Matter for GitHub Workflow
title: "GitHub Pages Documentation Deployment"
name: "gh-pages.yml"
description: "Build & deploy project docs to GitHub Pages via Sphinx & Nox"
category: workflow
usage: "Automatically triggered on push to main branch"
behavior: "Builds documentation and deploys to GitHub Pages"
inputs: "Source documentation files"
outputs: "Deployed documentation on GitHub Pages"
dependencies: "Poetry, Nox, Sphinx"
author: "LedgerBase Team"
last_modified: "2023-11-15"
changelog: "Initial migration to front-matter format"
tags: [docs, deployment, github-pages]
---

name: 📚 Build & Deploy Docs

on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  prepare:
    name: Prepare Poetry & Assured OSS
    uses: ./.github/workflows/templates/prepare-poetry.yml
    with:
      GCP_SA_JSON: ${{ secrets.GCP_SA_JSON }}
    secrets:
      GCP_SA_JSON: ${{ secrets.GCP_SA_JSON }}

  docs:
    name: Build & Deploy Docs
    needs: prepare
    runs-on: ubuntu-22.04
    permissions:
      contents: write

    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0
        with:
          egress-policy: audit

      - name: Checkout repo
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Verify no public PyPI fallbacks
        run: poetry run nox -s verify_assured

      - name: Build & collect docs via Nox
        run: poetry run nox -s build_docs

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/_build/html
          publish_branch: gh-pages
          user_name: "LedgerBase Bot"
          user_email: "ci@ledgerbase.example.com"