InvokeAI/.github/workflows/deploy-docs.yml

name: 'docs'

on:
  push:
    branches:
      - 'main'
  pull_request:
    types:
      - 'ready_for_review'
      - 'opened'
      - 'synchronize'
  # main deploys to v7.invoke.ai (invoke-ai/docs-v7); invoke.ai is deployed from the v6-bugfixes branch.
  workflow_dispatch:

permissions:
  contents: read
  pull-requests: read

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

jobs:
  changes:
    runs-on: blacksmith-4vcpu-ubuntu-2404
    outputs:
      docs: ${{ steps.manual.outputs.docs || steps.filter.outputs.docs }}
    steps:
      - name: checkout
        uses: useblacksmith/checkout@v1
        with:
          fetch-depth: 0

      # Deploy-branch pushes always rebuild: with cancel-in-progress, a later push that skipped
      # the build would cancel an earlier docs push's deploy and leave its changes unpublished.
      - name: mark push or manual run
        if: github.event_name != 'pull_request'
        id: manual
        run: echo "docs=true" >> "$GITHUB_OUTPUT"

      - name: detect docs-related changes
        if: github.event_name == 'pull_request'
        id: filter
        uses: dorny/paths-filter@v3
        with:
          filters: |
            docs:
              - '.github/workflows/deploy-docs.yml'
              - 'docs/**'
              - 'scripts/generate_docs_json.py'
              - 'invokeai/app/**'
              - 'invokeai/backend/**'
              - 'pyproject.toml'
              - 'uv.lock'

  check-and-build:
    needs: changes
    if: |
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'pull_request' &&
        github.event.pull_request.draft == false &&
        needs.changes.outputs.docs == 'true') ||
      (github.event_name == 'push' && needs.changes.outputs.docs == 'true')
    runs-on: blacksmith-4vcpu-ubuntu-2204
    timeout-minutes: 20
    steps:
      - name: checkout
        uses: useblacksmith/checkout@v1

      # Python (needed for generate-docs-data)
      - name: setup uv
        uses: astral-sh/[email protected]
        with:
          version: '0.11.28'  # When updating this, make sure the version in launcher's package.json gets updated too.
          enable-cache: true
          python-version: '3.12'

      - name: setup python
        uses: actions/setup-python@v6
        with:
          python-version: '3.12'

      # generate_docs_json.py only needs the invokeai package importable
      # (pydantic + invokeai.app/backend). Skip the [test] extra to keep CI fast.
      - name: install python dependencies
        run: uv sync --frozen

      # Node (needed for docs build)
      - name: setup node
        uses: actions/setup-node@v6
        with:
          node-version: '22'

      - name: setup pnpm
        uses: pnpm/action-setup@v6
        with:
          version: 10
          run_install: false

      - name: install docs dependencies
        run: pnpm install --prefer-frozen-lockfile
        working-directory: docs

      # Checks
      - name: test docs tooling
        run: pnpm test
        working-directory: docs

      - name: verify generated docs data
        run: pnpm run check-docs-data
        working-directory: docs

      - name: build docs
        run: pnpm build
        working-directory: docs
        env:
          DEPLOY_TARGET: custom
          ENABLE_ANALYTICS: ${{ github.ref == 'refs/heads/main' }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: verify deploy output
        run: pnpm run check-deploy-output
        working-directory: docs
        env:
          DEPLOY_TARGET: custom

      # Upload artifact for deploy (main branch only)
      - name: upload site artifact
        if: github.ref == 'refs/heads/main'
        uses: actions/upload-artifact@v7
        with:
          name: docs-site
          path: docs/dist
          include-hidden-files: true
          retention-days: 1

  # GitHub Pages serves one custom domain per repository, and this repository's is invoke.ai (v6),
  # so the v7 site is published to the gh-pages branch of invoke-ai/docs-v7 with a deploy key.
  deploy:
    if: github.ref == 'refs/heads/main'
    needs: check-and-build
    runs-on: blacksmith-4vcpu-ubuntu-2404
    permissions:
      contents: read
    environment:
      name: docs-v7
      url: https://v7.invoke.ai
    steps:
      - name: download site artifact
        uses: actions/download-artifact@v8
        with:
          name: docs-site
          path: site

      - name: publish to invoke-ai/docs-v7
        env:
          DEPLOY_KEY: ${{ secrets.DOCS_V7_DEPLOY_KEY }}
          GH_TOKEN: ${{ github.token }}
        working-directory: site
        run: |
          set -euo pipefail
          # The custom domain comes from CNAME; .nojekyll keeps branch-based Pages from dropping _astro/.
          test "$(cat CNAME)" = "v7.invoke.ai"
          touch .nojekyll

          mkdir -p ~/.ssh
          gh api meta --jq '.ssh_keys[] | "github.com " + .' > ~/.ssh/known_hosts
          eval "$(ssh-agent -s)"
          ssh-add - <<< "$DEPLOY_KEY"

          git init -q -b gh-pages
          git add -A
          git -c user.name='github-actions[bot]' -c user.email='41898282+github-actions[bot]@users.noreply.github.com' \
            commit -q -m "Deploy invoke-ai/InvokeAI@${GITHUB_SHA}"
          git push --force [email protected]:invoke-ai/docs-v7.git gh-pages