deploy-docs.yml

# ==============================================================================
# HOW TO USE THIS WORKFLOW:
# ==============================================================================
# 1. PUSH TO 'main' BRANCH:
#    - Automatically updates the '/main/' folder on the gh-pages branch.
#    - NOTE: This only triggers if files in 'docs/' or 'mkdocs.yml' changed.
#    - Use this for "Bleeding Edge" documentation.
#
# 2. PUBLISH A RELEASE:
#    - Automatically creates a folder named after the tag (e.g., /v2.5.0/).
#    - Automatically points the '/latest/' folder (alias) to that new tag.
#    - Use this for official, stable version launches.
#
# 3. MANUAL RUN (GitHub Actions UI -> "Run workflow"):
#    - "Version": The folder name you want to create or overwrite (e.g., v2.5.0).
#    - "Alias": (Optional) The redirect folder you want to point to that version
#      (e.g., enter 'latest' to move the latest pointer to the version above).
#    - Use this to FIX an existing version folder without making a new release.
# ==============================================================================

name: Deploy Documentation

concurrency:
  group: deploy-docs
  cancel-in-progress: false

on:
  release:
    types: [published]
  push:
    branches:
      - main
  # checkov:skip=CKV_GHA_7: Inputs are validated and sanitized via regex below to prevent injection.
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to deploy (e.g., v2.5.0 or main)'
        required: true
        default: 'main'
      alias:
        description: 'Alias to update (e.g., latest)'
        required: false
        default: ''

permissions:
  contents: read

jobs:
  check-for-changes:
    if: github.event_name == 'push'
    name: Check for changes
    runs-on: ubuntu-latest
    outputs:
      changed: ${{ steps.check_files.outputs.any_changed }}
    steps:
      - name: Checkout Code
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Check for changed documentation files
        id: check_files
        uses: tj-actions/changed-files@v47
        with:
          files: |
            docs/**
            mkdocs.yml

  deploy:
    name: Deploy MkDocs Site
    permissions:
      contents: write
    runs-on: ubuntu-latest
    timeout-minutes: 10
    needs: [check-for-changes]
    if: |
      always() &&
      !cancelled() &&
      (github.event_name != 'push' || needs.check-for-changes.outputs.changed == 'true')
    env:
      CI_COMMIT_AUTHOR: 'CI Bot'
      CI_COMMIT_EMAIL: 'ci@noreply.github.com'
      CI_COMMIT_MESSAGE: 'Continuous Integration - Deploy Documentation'

    steps:
      - name: Validate Inputs
        id: validation
        env:
          MY_VERSION: ${{ github.event.inputs.version }}
          MY_ALIAS: ${{ github.event.inputs.alias }}
        # language=bash
        run: |
          if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
            if [[ ! "$MY_VERSION" =~ ^[a-zA-Z0-9._-]+$ ]]; then
              echo "::error::Invalid version name: $MY_VERSION. Only alphanumeric, dots, and hyphens allowed."
              exit 1
            fi
            if [[ -n "$MY_ALIAS" && ! "$MY_ALIAS" =~ ^[a-zA-Z0-9._-]+$ ]]; then
              echo "::error::Invalid alias name: $MY_ALIAS. Only alphanumeric, dots, and hyphens allowed."
              exit 1
            fi
          fi

          if [ "${{ github.event_name }}" == "release" ]; then
            TARGET_REF="${{ github.event.release.tag_name }}"
          elif [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
            TARGET_REF="${{ github.event.inputs.version }}"
          else
            TARGET_REF="${{ github.ref }}"
          fi

          echo "target_version=$MY_VERSION" >> "$GITHUB_OUTPUT"
          echo "target_alias=$MY_ALIAS" >> "$GITHUB_OUTPUT"
          echo "target_ref=$TARGET_REF" >> "$GITHUB_OUTPUT"

      - name: Generate GitHub App Token
        id: generate_token
        uses: actions/create-github-app-token@v3
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

      - name: Checkout Code
        uses: actions/checkout@v6
        with:
          token: ${{ steps.generate_token.outputs.token }}
          ref: ${{ steps.validation.outputs.target_ref }}
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: '3.x'
          cache: 'pip'

      - name: Install MkDocs and dependencies
        run: pip install -r requirements.txt

      - name: Deploy Docs to GitHub Pages
        # language=bash
        run: |
          git config --global user.name "${{ env.CI_COMMIT_AUTHOR }}"
          git config --global user.email "${{ env.CI_COMMIT_EMAIL }}"
          git remote set-url origin https://x-access-token:${{ steps.generate_token.outputs.token }}@github.com/DigiLive/mushroom-strategy.git

          if ! git fetch origin gh-pages --depth=1 2>/dev/null; then
          echo "::notice::gh-pages branch does not exist yet. mike will create it."
          fi

          if [ "${{ github.event_name }}" == "release" ]; then
            # Release: Create a permanent version folder and update latest alias.
            mike deploy --push --update-aliases "${{ github.event.release.tag_name }}" latest
          elif [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
            if [ -n  "${{ steps.validation.outputs.target_alias }}" ]; then
              mike deploy --push --update-aliases "${{ steps.validation.outputs.target_version }}" "${{ steps.validation.outputs.target_alias }}"
            else
              mike deploy --push "${{ steps.validation.outputs.target_version }}"
            fi
          else
            # Push: Update the /main/ folder
            mike deploy --push main
          fi