Standardize upstream CLI reference syncing

.github/workflows/sync-upstream-cli.yml

@@ -0,0 +1,140 @@
+# Syncs CLI reference YAML from upstream repositories.
+#
+# Runs on a schedule to auto-detect new releases, or manually via workflow_dispatch.
+# For each configured upstream repo, runs its docs bake target via git context
+# to generate YAML, copies it to data/cli/<folder>/, and opens a PR.
+#
+# To add a new repo: add an entry to the matrix and to the workflow_dispatch options.
+
+name: sync-upstream-cli
+
+on:
+  schedule:
+    # Check for new upstream releases daily at 02:00 UTC
+    - cron: "0 2 * * *"
+  workflow_dispatch:
+    inputs:
+      repo:
+        description: "Upstream repo"
+        required: true
+        type: choice
+        options:
+          - docker/buildx
+          - docker/compose
+          - docker/model-runner
+      version:
+        description: "Git tag (e.g., v0.33.0). Leave empty for latest release."
+        required: false
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+
+env:
+  SETUP_BUILDX_VERSION: "edge"
+  SETUP_BUILDKIT_IMAGE: "moby/buildkit:latest"
+
+jobs:
+  sync:
+    runs-on: ubuntu-24.04
+    if: ${{ !inputs.repo || inputs.repo == matrix.repo }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - repo: docker/buildx
+            folder: buildx
+            target: update-docs
+            yaml_glob: out/reference
+
+          - repo: docker/compose
+            folder: compose
+            target: docs-update
+            yaml_glob: out/reference
+
+          - repo: docker/model-runner
+            folder: model
+            target: update-docs
+            files: cmd/cli/docker-bake.hcl
+            yaml_glob: "."
+    steps:
+      - name: Resolve version
+        id: version
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if [ -n "${{ inputs.version }}" ]; then
+            echo "tag=${{ inputs.version }}" >> "$GITHUB_OUTPUT"
+          else
+            TAG=$(gh api "repos/${{ matrix.repo }}/releases/latest" --jq '.tag_name')
+            echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout docker/docs
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Check if already synced
+        id: check
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.version.outputs.tag }}
+        run: |
+          EXISTING=$(gh pr list --state all \
+            --search "cli(${{ matrix.folder }}): sync docs $VERSION in:title" \
+            --json state --jq '.[0].state // empty')
+
+          if [ "$EXISTING" = "MERGED" ] || [ "$EXISTING" = "CLOSED" ]; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "Already synced ${{ matrix.repo }} $VERSION" >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Set up Docker Buildx
+        if: steps.check.outputs.skip != 'true'
+        uses: docker/setup-buildx-action@v4
+        with:
+          version: ${{ env.SETUP_BUILDX_VERSION }}
+          driver-opts: image=${{ env.SETUP_BUILDKIT_IMAGE }}
+
+      - name: Generate YAML
+        if: steps.check.outputs.skip != 'true'
+        uses: docker/bake-action@v7
+        with:
+          source: "${{ github.server_url }}/${{ matrix.repo }}.git#${{ steps.version.outputs.tag }}"
+          files: ${{ matrix.files || '' }}
+          targets: ${{ matrix.target }}
+          provenance: false
+          set: |
+            *.output=/tmp/docs-release
+        env:
+          DOCS_FORMATS: yaml
+
+      - name: Copy data files
+        if: steps.check.outputs.skip != 'true'
+        run: |
+          mkdir -p "data/cli/${{ matrix.folder }}"
+          rm -f "data/cli/${{ matrix.folder }}"/*.yaml
+          cp /tmp/docs-release/${{ matrix.yaml_glob }}/*.yaml "data/cli/${{ matrix.folder }}/"
+
+      - name: Create pull request
+        if: steps.check.outputs.skip != 'true'
+        uses: peter-evans/create-pull-request@v7
+        with:
+          branch: bot/sync-${{ matrix.folder }}-cli
+          title: "cli(${{ matrix.folder }}): sync docs ${{ steps.version.outputs.tag }}"
+          commit-message: "cli(${{ matrix.folder }}): sync docs ${{ steps.version.outputs.tag }}"
+          body: |
+            ## Summary
+
+            Automated sync of CLI reference docs.
+
+            | | |
+            |---|---|
+            | **Tool** | `${{ matrix.folder }}` |
+            | **Version** | `${{ steps.version.outputs.tag }}` |
+            | **Source** | [${{ matrix.repo }}@${{ steps.version.outputs.tag }}](${{ github.server_url }}/${{ matrix.repo }}/tree/${{ steps.version.outputs.tag }}) |
+          delete-branch: true