update-cli-docs.yml

name: Update CLI documentation

on:
  repository_dispatch:
    types: [cli-release-published]
  workflow_dispatch:
    inputs:
      tag_name:
        description: 'tower-cli release tag; leave blank for the latest stable release'
        required: false
        type: string
      create_pull_request:
        description: 'Create or update a draft PR when the resolved release is stable'
        required: true
        default: true
        type: boolean

permissions:
  contents: read

concurrency:
  group: cli-docs-${{ github.event.client_payload.tag_name || inputs.tag_name || 'latest' }}
  cancel-in-progress: false

jobs:
  update-cli-docs:
    name: Extract and generate CLI docs
    runs-on: ubuntu-latest
    timeout-minutes: 20

    steps:
      - name: Validate request
        id: request
        env:
          EVENT_NAME: ${{ github.event_name }}
          DISPATCH_REPOSITORY: ${{ github.event.client_payload.repository }}
          DISPATCH_RELEASE_ID: ${{ github.event.client_payload.release_id }}
          DISPATCH_TAG_NAME: ${{ github.event.client_payload.tag_name }}
          INPUT_TAG_NAME: ${{ inputs.tag_name }}
          INPUT_CREATE_PULL_REQUEST: ${{ inputs.create_pull_request }}
        run: |
          if [ "$EVENT_NAME" = "repository_dispatch" ]; then
            if [ "$DISPATCH_REPOSITORY" != "seqeralabs/tower-cli" ]; then
              echo "Unexpected source repository: $DISPATCH_REPOSITORY"
              exit 1
            fi
            if [ -z "$DISPATCH_RELEASE_ID" ] || [ -z "$DISPATCH_TAG_NAME" ]; then
              echo "The dispatch payload must include release_id and tag_name"
              exit 1
            fi
            create_pull_request=true
            require_stable=true
            release_id="$DISPATCH_RELEASE_ID"
            tag_name="$DISPATCH_TAG_NAME"
          else
            create_pull_request="$INPUT_CREATE_PULL_REQUEST"
            require_stable=false
            release_id=""
            tag_name="$INPUT_TAG_NAME"
          fi
          {
            echo "create_pull_request=$create_pull_request"
            echo "require_stable=$require_stable"
            echo "release_id=$release_id"
            echo "tag_name=$tag_name"
          } >> "$GITHUB_OUTPUT"

      - name: Checkout docs repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # ratchet:actions/checkout@v7.0.1
        with:
          persist-credentials: false

      - name: Set up Java
        uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5.7.0
        with:
          distribution: temurin
          java-version: '21'

      - name: Set up Python
        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # ratchet:actions/setup-python@v6.3.0
        with:
          python-version: '3.14'

      - name: Read previously documented release
        id: previous
        run: |
          if [ -f platform-cli-docs/release.json ]; then
            echo "tag_name=$(jq -r '.tag_name // empty' platform-cli-docs/release.json)" >> "$GITHUB_OUTPUT"
          else
            echo "tag_name=" >> "$GITHUB_OUTPUT"
          fi

      - name: Download and extract release metadata
        id: prepare
        env:
          GH_TOKEN: ${{ github.token }}
          REQUEST_TAG_NAME: ${{ steps.request.outputs.tag_name }}
          REQUEST_RELEASE_ID: ${{ steps.request.outputs.release_id }}
          PREVIOUS_TAG_NAME: ${{ steps.previous.outputs.tag_name }}
          REQUIRE_STABLE: ${{ steps.request.outputs.require_stable }}
        run: |
          args=(--work-dir "$RUNNER_TEMP/cli-docs" --github-output "$GITHUB_OUTPUT")
          if [ -n "$REQUEST_TAG_NAME" ]; then
            args+=(--tag-name "$REQUEST_TAG_NAME")
          fi
          if [ -n "$REQUEST_RELEASE_ID" ]; then
            args+=(--release-id "$REQUEST_RELEASE_ID")
          fi
          if [ -n "$PREVIOUS_TAG_NAME" ]; then
            args+=(--previous-tag "$PREVIOUS_TAG_NAME")
          fi
          if [ "$REQUIRE_STABLE" = "true" ]; then
            args+=(--require-stable)
          fi
          python3 platform-cli-docs/scripts/prepare-cli-release.py "${args[@]}"

      - name: Compare command models
        env:
          CURRENT_METADATA: ${{ steps.prepare.outputs.metadata_path }}
          PREVIOUS_METADATA: ${{ steps.prepare.outputs.previous_metadata_path }}
        run: |
          args=("$CURRENT_METADATA")
          if [ -n "$PREVIOUS_METADATA" ]; then
            args+=("$PREVIOUS_METADATA")
          fi
          python3 platform-cli-docs/scripts/compare-metadata.py \
            "${args[@]}" \
            --output "$RUNNER_TEMP/cli-docs/comparison-report.md"

      - name: Generate reference documentation
        env:
          CURRENT_METADATA: ${{ steps.prepare.outputs.metadata_path }}
        run: |
          python3 platform-cli-docs/scripts/generate-cli-docs.py \
            --metadata "$CURRENT_METADATA" \
            --overlays platform-cli-docs/overlays \
            --output platform-cli-docs/docs/reference \
            --sidebar platform-cli-docs/docs/sidebar/sidebar.js

      - name: Record documented release
        env:
          RELEASE_RECORD: ${{ steps.prepare.outputs.release_record_path }}
        run: |
          python3 platform-cli-docs/scripts/apply-cli-release.py \
            --release-record "$RELEASE_RECORD" \
            --manifest platform-cli-docs/release.json \
            --notice-file platform-cli-docs/docs/overview.md \
            --notice-file platform-cli-docs/docs/commands-reference.md

      - name: Upload extraction evidence
        if: always() && steps.prepare.outcome == 'success'
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # ratchet:actions/upload-artifact@v4.6.2
        with:
          name: cli-docs-metadata-${{ steps.prepare.outputs.branch_ref }}
          path: |
            ${{ runner.temp }}/cli-docs/cli-metadata-current.json
            ${{ runner.temp }}/cli-docs/cli-metadata-previous.json
            ${{ runner.temp }}/cli-docs/comparison-report.md
            ${{ runner.temp }}/cli-docs/release.json
          if-no-files-found: error
          retention-days: 30

      - name: Check for changes
        id: changes
        run: |
          if [ -n "$(git status --porcelain -- platform-cli-docs)" ]; then
            echo "has_changes=true" >> "$GITHUB_OUTPUT"
            git diff --stat -- platform-cli-docs
            git status --short -- platform-cli-docs
          else
            echo "has_changes=false" >> "$GITHUB_OUTPUT"
            echo "CLI documentation is already current"
          fi

      - name: Generate docs app token
        if: >-
          steps.changes.outputs.has_changes == 'true' &&
          steps.prepare.outputs.prerelease == 'false' &&
          steps.request.outputs.create_pull_request == 'true'
        id: docs-app-token
        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
        with:
          app-id: ${{ secrets.DOCS_BOT_APP_ID }}
          private-key: ${{ secrets.DOCS_BOT_APP_PRIVATE_KEY }}
          owner: seqeralabs
          repositories: docs

      - name: Create draft pull request
        if: >-
          steps.changes.outputs.has_changes == 'true' &&
          steps.prepare.outputs.prerelease == 'false' &&
          steps.request.outputs.create_pull_request == 'true'
        uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # ratchet:peter-evans/create-pull-request@v8.1.1
        with:
          token: ${{ steps.docs-app-token.outputs.token }}
          add-paths: platform-cli-docs
          branch: cli-docs-${{ steps.prepare.outputs.branch_ref }}
          delete-branch: true
          draft: true
          labels: |
            documentation
            cli
            auto-generated
          commit-message: 'Update CLI documentation for ${{ steps.prepare.outputs.tag_name }}'
          title: 'CLI docs: Update for ${{ steps.prepare.outputs.tag_name }}'
          body-path: ${{ runner.temp }}/cli-docs/comparison-report.md

      - name: Report dry run
        if: >-
          steps.request.outputs.create_pull_request != 'true' ||
          steps.prepare.outputs.prerelease == 'true'
        run: |
          echo "Extraction and generation completed without creating a PR."
          echo "Release: ${{ steps.prepare.outputs.tag_name }}"
          echo "Prerelease: ${{ steps.prepare.outputs.prerelease }}"