deploy.yaml

name: Deploy Docusaurus to GitHub Pages

on:
  push:
    branches:
      - main
    paths:
      - 'reference/**'
      - 'reference_versioned_docs/**'
      - 'reference_versioned_sidebars/**'
      - 'reference_versions.json'
      - 'docs/**'
      - 'fabric/**'
      - 'learn/**'
      - 'release-notes/**'
      - 'src/**'
      - 'static/**'
      - 'versioned_docs/**'
      - 'versioned_sidebars/**'
      - 'docusaurus.config.ts'
      - 'package-lock.json'
      - 'package.json'
      - 'historic-redirects.ts'
      - 'redirects.ts'
      - 'sidebars*.ts'
      - 'versions.json'
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Concurrency configuration to manage parallel workflow runs
concurrency:
  group: production-deploy
  cancel-in-progress: true

jobs:
  build:
    name: Build Docusaurus
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: '24'
          cache: 'npm'
          cache-dependency-path: 'package-lock.json'

      - name: Install dependencies
        run: |
          echo "Installing dependencies from $(pwd)"
          npm ci || (echo "npm ci failed, uploading logs" && exit 1)

      - name: Build Docusaurus site
        env:
          DOCUSAURUS_ROUTE_BASE_PATH: ${{ vars.DOCUSAURUS_ROUTE_BASE_PATH }}
          DOCUSAURUS_BASE_URL: ${{ vars.DOCUSAURUS_BASE_URL }}
          DOCUSAURUS_URL: ${{ vars.DOCUSAURUS_URL }}
          ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }}
          ALGOLIA_SEARCH_KEY: ${{ secrets.ALGOLIA_SEARCH_KEY }}
          ALGOLIA_INDEX_NAME: ${{ secrets.ALGOLIA_INDEX_NAME }}
          GA4_TRACKING_ID: ${{ secrets.GA4_TRACKING_ID }}
        run: |
          echo "Building Docusaurus site..."
          echo "Using DOCUSAURUS_ROUTE_BASE_PATH: $DOCUSAURUS_ROUTE_BASE_PATH"
          echo "Using DOCUSAURUS_BASE_URL: $DOCUSAURUS_BASE_URL"
          echo "Using DOCUSAURUS_URL: $DOCUSAURUS_URL"
          npm run build || (echo "Site build failed" && exit 1)

      - name: Verify flat-markdown export
        run: |
          # @signalwire/docusaurus-plugin-llms-txt should have produced one
          # .md file per HTML page plus an llms.txt index. This artifact is
          # consumed by @harperfast/skills (and any third-party LLM tooling).
          # Fail the build loudly if it didn't run or produced no output.
          set -euo pipefail
          failures=0
          for dir in learn reference fabric release-notes; do
            count=$(find "build/$dir" -name '*.md' 2>/dev/null | wc -l | tr -d ' ')
            if [ "$count" -lt 1 ]; then
              echo "::error::No .md files generated under build/$dir/ — llms-txt plugin failed for this docs instance"
              failures=$((failures + 1))
            else
              echo "build/$dir: $count .md files"
            fi
          done
          for f in build/llms.txt build/llms-full.txt; do
            if [ ! -f "$f" ]; then
              echo "::error::Expected artifact $f is missing"
              failures=$((failures + 1))
            fi
          done
          if [ "$failures" -gt 0 ]; then
            exit 1
          fi
          echo "✓ Flat-markdown export verified"

      - name: Upload npm logs on failure
        if: failure()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: npm-logs
          path: |
            ~/.npm/_logs/

      - name: Upload Build Artifact
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: build

  deploy:
    needs: build
    name: Deploy to GitHub Pages
    runs-on: ubuntu-latest

    permissions:
      pages: write
      id-token: write

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

  # Notify the skills repo that docs changed, so it can regenerate its
  # docs-driven rules against the just-deployed content. See the
  # generate.yaml workflow in HarperFast/skills (Phase 2 of the
  # docs-driven-skills plan).
  #
  # Authenticates as the org-owned "harper-skills-sync" GitHub App, minting
  # a token scoped to HarperFast/skills (the default GITHUB_TOKEN is scoped
  # to this repo only and cannot dispatch cross-repo). The App must be
  # installed on the skills repo; this repo holds its SKILLS_SYNC_APP_ID /
  # SKILLS_SYNC_APP_PRIVATE_KEY secrets. If the App is ever removed, the
  # skills repo's weekly cron is the safety net.
  notify-skills:
    needs: deploy
    name: Notify skills repo
    runs-on: ubuntu-latest
    steps:
      - name: Mint app token for skills
        id: app-token
        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
        with:
          app-id: ${{ secrets.SKILLS_SYNC_APP_ID }}
          private-key: ${{ secrets.SKILLS_SYNC_APP_PRIVATE_KEY }}
          owner: HarperFast
          repositories: skills

      - name: Dispatch docs-updated to HarperFast/skills
        env:
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
        run: |
          gh api repos/HarperFast/skills/dispatches \
            -f event_type=docs-updated \
            -F client_payload[sha]=${{ github.sha }}