publish-docs.yml

name: Docs/Build and Publish

on:
  push:
    branches: ['release/*', 'develop']
  workflow_dispatch:
    inputs:
      ref:
        description: 'Branch or tag to deploy'
        required: false
        default: 'release/stable'
  release:
    types: [published]

# Ensure only one concurrent deployment
concurrency:
  group: ${{ github.workflow }}
  cancel-in-progress: false

# Restrict permissions by default
permissions:
  contents: write # Required for committing to gh-pages
  pages: write # Required for deploying to Pages
  pull-requests: write # Required for PR comments

jobs:
  docs-build-deploy:
    name: Publish Docs
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - name: 📥 Checkout the repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          fetch-depth: 0
          ref: ${{ github.event.inputs.ref || github.ref }}

      - name: 🐍 Install uv and set Python
        uses: astral-sh/setup-uv@5a095e7a2014a4212f075830d4f7277575a9d098  # v7.3.1
        with:
          python-version: "3.10"
          activate-environment: true

      - name: 🏗️ Install dependencies
        run: uv sync --frozen --group docs

      - name: ⚙️ Configure git for github-actions
        run: |
          git config --global user.name "${{ github.actor }}"
          git config --global user.email "${{ github.actor }}@users.noreply.github.com"

      - name: 🚀 Deploy Development Docs
        if: (github.event_name == 'push' && github.ref == 'refs/heads/develop')
        env:
          MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.GITHUB_TOKEN }}
        run: uv run mike deploy --push develop

      - name: 🚀 Deploy Custom Ref Docs
        if: github.event_name == 'workflow_dispatch'
        env:
          MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.GITHUB_TOKEN }}
        run: |
          REF_NAME="${{ github.event.inputs.ref }}"
          # If it's a full ref like refs/heads/branch or refs/tags/tag, extract the name
          CLEAN_REF=$(echo "$REF_NAME" | sed 's|^refs/[^/]*/||')
          uv run mike deploy --push $CLEAN_REF

      - name: 🚀 Deploy Release Docs
        if: github.event_name == 'release' && github.event.action == 'published'
        env:
          MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.GITHUB_TOKEN }}
        run: |
          latest_tag=$(git describe --tags `git rev-list --tags --max-count=1`)
          uv run mike deploy --push --update-aliases $latest_tag latest
          uv run mike set-default --push latest