docs.yml

# =============================================================
# Deploy Documentation
#
# Deploy MkDocs to GitHub Pages on push to main.
#
# Triggers on:
#   - Push to main branch (any file in docs/ or mkdocs.yml)
#   - Manual trigger via Actions tab
#
# Uses pip to install mkdocs-material, builds the site,
# and deploys to the gh-pages branch.
# =============================================================

name: Deploy Documentation 📚

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - 'CHANGELOG.md'
  pull_request:
    branches:
      - main
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - 'CHANGELOG.md'
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read # Minimum global permission

jobs:
  deploy:
    name: Build & Deploy Docs 🚀
    if: github.event_name != 'workflow_dispatch' || github.actor == github.repository_owner
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: write # Needed to push to gh-pages branch
    steps:
      - name: Harden Runner 🛡️
        uses: step-security/harden-runner@a5ad31d6a139d249332a2605b85202e8c0b78450 # v2.19.1
        with:
          egress-policy: audit

      - name: Checkout repository 📥
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          # Required for mkdocs-material "Last Updated" feature and git-cliff inclusion
          fetch-depth: 0
          persist-credentials: false

      - name: Create Bot Token 🤖🔑
        id: generate_token
        uses: ./.github/actions/setup-bot
        with:
          client-id: ${{ secrets.CHITRANK_BOT_CLIENT_ID }}
          private-key: ${{ secrets.CHITRANK_BOT_PRIVATE_KEY }}

      - name: Configure Authenticated Git 🔧
        env:
          TOKEN: ${{ steps.generate_token.outputs.token }}
          REPO: ${{ github.repository }}
        run: |
          git remote set-url origin "https://x-access-token:${TOKEN}@github.com/${REPO}"

      - name: Set up Python 🐍
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: '3.14'
          cache: 'pip'

      - name: Install MkDocs Material 🛠️
        run: |
          python -m pip install --upgrade pip
          pip install --prefer-binary -r requirements.txt

      # Copy root files into docs/ so MkDocs can include them.
      # The source of truth stays at the root.
      # These files are ignored by git in docs/ and only exist during CI build.
      - name: Copy transient docs 📝
        run: |
          cp CHANGELOG.md docs/changelog.md
          cp CODE_OF_CONDUCT.md docs/code-of-conduct.md

      # Configure git so mkdocs gh-deploy can push to gh-pages branch.
      - name: Configure git 🔧
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Build Documentation 🏗️
        run: mkdocs build

      - name: Deploy to GitHub Pages 🌐
        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        run: mkdocs gh-deploy --force