sync_docs.yml

name: Sync the Docs
run-name: >-
  Sync the Docs: version ${{ inputs.version }}

on:
  workflow_dispatch:
    inputs:
      version:
        description: Pants Version to use (should be the full version, like "2.20.1rc2")
        required: true
        type: string

      reviewer:
        description: |
          Who to assign as PR reviewer (default: you)
        required: false
        type: string

env:
  NODE_VERSION: 24.x

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      # Generate `help-all.json`
      - name: Pants on!
        run: |
          curl --proto '=https' --tlsv1.2 -fsSL https://static.pantsbuild.org/setup/get-pants.sh | bash
          echo "$HOME/.local/bin" >> $GITHUB_PATH
      - name: Generate help JSON
        # First run `help-all` which will contain the list of every backend in the `name_to_backend_help_info` object,
        # then run it again with every backend enabled.
        run: |
          touch pants.toml
          PANTS_VERSION="${{ inputs.version }}" pants help-all > help-all.json
          PANTS_VERSION="${{ inputs.version }}" pants --backend-packages=[$(jq -r '.name_to_backend_help_info | keys_unsorted | map("\"" + . + "\"") | join(",")' help-all.json)] help-all > help-all.json

      # Checkout both repos
      - name: Checkout pants repo
        uses: actions/checkout@v7
        with:
          repository: pantsbuild/pants
          ref: release_${{ inputs.version }}
          fetch-depth: 0
          path: pants

      - name: Checkout docs repo
        uses: actions/checkout@v7
        with:
          repository: pantsbuild/pantsbuild.org
          fetch-depth: 0
          path: pantsbuild.org

      # Setup `node` and and `pnpm`
      - name: Install pnpm
        uses: pnpm/action-setup@v6
        with:
          run_install: false
          package_json_file: "pantsbuild.org/package.json"

      - name: Setup Node.js ${{ env.NODE_VERSION }}
        uses: actions/setup-node@v6
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: "pnpm"
          cache-dependency-path: "pantsbuild.org/pnpm-lock.yaml"

      - name: Get pnpm store directory
        id: pnpm-cache
        shell: bash
        run: |
          echo "PNPM_STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT

      - name: Install dependencies
        run: pnpm install --frozen-lockfile
        working-directory: pantsbuild.org

      # Calculate destination
      - name: Calculate destination
        id: get-destination-dir
        run: |
          BASE_VERSION=$(echo "${{ inputs.version }}" | sed -E 's/^([0-9]+)\.([0-9]+)\.\w+.*/\1.\2/')
          DESTINATION_DIR="versioned_docs/version-$BASE_VERSION"
          if [ ! -d "$DESTINATION_DIR" ]; then
            if [[ "${{ inputs.version }}" =~ .*\.0a0$ ]]; then
              # a0 => we've cut a new branch from `main`, so make a new version
              pnpm docusaurus docs:version $BASE_VERSION
            else
              DESTINATION_DIR="docs"
            fi
          fi
          echo "DESTINATION_DIR=$(echo "$DESTINATION_DIR")" | tee -a "${GITHUB_OUTPUT}"
        working-directory: pantsbuild.org
      - run: |
          rm -rf "pantsbuild.org/${{ steps.get-destination-dir.outputs.DESTINATION_DIR }}"
          mkdir -p "pantsbuild.org/${{ steps.get-destination-dir.outputs.DESTINATION_DIR }}/reference"
          cp help-all.json "pantsbuild.org/${{ steps.get-destination-dir.outputs.DESTINATION_DIR }}/reference"

      # Generate reference docs
      - name: Generate reference docs
        run: pnpm generate-reference "${{ steps.get-destination-dir.outputs.DESTINATION_DIR }}"
        working-directory: pantsbuild.org

      # Sync the docs repo
      - run: cp -r pants/docs/docs "pantsbuild.org/${{ steps.get-destination-dir.outputs.DESTINATION_DIR }}"

      # Commit and create a PR.
      #
      # This is always performed (even on failure, and even with no code changes), as a mechanism to
      # surface failures to the reviewer. This workflow is usually triggered by automation in the
      # background after a release, and it is easy for the release manager to forget to follow up
      # about the docs (if there's a silent failure).
      - name: Commit changes
        if: always()
        run: |
          git config --local user.email "pantsbuild+github-automation@gmail.com"
          git config --local user.name "Worker Pants (Pantsbuild GitHub Automation Bot)"
          git checkout -b "automation/sync-${{ inputs.version }}"
          git add -A
          git commit -m "Update docs site for version ${{ inputs.version }}" -a --allow-empty
          git push -u origin "automation/sync-${{ inputs.version }}"
        working-directory: pantsbuild.org
      - name: Prepare PR text
        if: always()
        run: |
          touch title-prefix.md
          echo "Docs from https://github.com/pantsbuild/pants/releases/tag/release_${{ inputs.version }}" > body.md
      # When the job is failing, add extra info to the PR body:
      - name: Append failure info
        if: failure()
        run: |
          echo "[FAILURE] " >> title-prefix.md
          {
            echo
            # (would be nice if there was a way to link to this job directly, but the required ID doesn't seem to be available via the context objects)
            echo "The sync_docs job failed part way through and may need debugging: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
            echo
            echo "Note: to retry the job, first close this PR and delete its branch."
          } >> body.md
      - name: Make a PR
        if: always()
        run: gh pr create --title "$(cat ../title-prefix.md)Update docs site for version ${{ inputs.version }}" --body-file=../body.md  --reviewer "${{ inputs.reviewer || github.actor }}" --label 'automation:sync-docs'
        env:
          GH_TOKEN: ${{ secrets.WORKER_PANTS_PR_PAT }}
        working-directory: pantsbuild.org