docs.yml

#
# Copyright (c) 2026 devlive-community/pipeforge
#
# Licensed under the MIT License. See the LICENSE file in the
# project root for full license text.
#
# Documentation site: content checks, lint, component tests, static build and Lighthouse on
# every change that can affect the site; deployment to GitHub Pages from main. Pull requests
# get the built site as a downloadable preview and the documentation coverage check.
# "docs-ok" is the required status check.

name: Docs

on:
  pull_request:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: docs-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  changes:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    outputs:
      docs: ${{ steps.detect.outputs.docs }}
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - id: detect
        run: bash .ci/changed-components.sh --github-output -v

  # Every feat / perf / breaking commit must update the pages mapped in docs-map.yaml.
  coverage:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v5
        with:
          node-version-file: .nvmrc
          cache: pnpm
      - run: pnpm install --frozen-lockfile --filter @pipeforge/docs...
      - env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: docs/scripts/check-docs-coverage.sh "$BASE_SHA" "$HEAD_SHA"

  build:
    needs: changes
    if: needs.changes.outputs.docs == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 20
    env:
      NEXT_TELEMETRY_DISABLED: 1
      DOCS_BASE_PATH: /${{ github.event.repository.name }}
      DOCS_SITE_URL: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}
    defaults:
      run:
        working-directory: docs
    steps:
      - uses: actions/checkout@v5
        with:
          # the changelog of plugin pages is read from the history of each plugin module
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v5
        with:
          node-version-file: .nvmrc
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm generate
      - run: pnpm check
      - run: pnpm test
      - run: pnpm build
      - run: pnpm lint
      - run: pnpm lighthouse
      - if: github.event_name == 'push' && github.ref == 'refs/heads/main'
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/out
      - if: github.event_name == 'pull_request'
        uses: actions/upload-artifact@v4
        with:
          name: docs-preview
          path: docs/out
          retention-days: 7

  deploy:
    needs: build
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

  docs-ok:
    if: always()
    needs: [changes, coverage, build, deploy]
    runs-on: ubuntu-latest
    timeout-minutes: 2
    steps:
      - env:
          RESULTS: ${{ join(needs.*.result, ' ') }}
        run: |
          echo "job results: $RESULTS"
          case " $RESULTS " in
            *" failure "*|*" cancelled "*) exit 1 ;;
          esac