RFC: standardize upstream CLI reference syncing

[dvdksn]

RFC: standardize how upstream repos sync CLI reference docs

This PR proposes a generic reusable workflow that upstream repos can call to push CLI reference YAML to data/cli/<folder>/ and open a PR. The goal is to replace the current patchwork of import mechanisms with a single, consistent pattern.

Problem

We currently have 4 different mechanisms for getting CLI reference YAML into data/cli/:

Mechanism	Used by
Hugo module mounts via _vendor/	compose, model-runner
Daily cron job (sync-cli-docs.sh) that clones + builds docker/cli	engine
Semi-manual commits alongside Hugo vendor	buildx
Fully manual commits, no automation	scout, mcp, desktop, dhi, sandbox, offload, secrets, debug, init

Proposed solution

One reusable workflow (sync-upstream-cli.yml) that shares input names with the existing validate-upstream.yml, so upstream repos get a consistent interface.

Auth: A dedicated GitHub App (docker-docs-sync) installed on docker/docs with contents:write + pull-requests:write. App credentials stored as org secrets, accessible to upstream repos. The calling workflow mints a short-lived token and passes it as a plain secret — the reusable workflow just receives a token string.

Example caller (e.g., docs-release.yml in an upstream repo):

jobs:
  # Generate YAML reference files (same step used for validate-upstream)
  docs-yaml:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: make generate-yaml-docs
      - uses: actions/upload-artifact@v4
        with:
          name: cli-yaml
          path: docs/yaml/*.yaml

  # Mint a short-lived token from the GitHub App
  token:
    runs-on: ubuntu-latest
    outputs:
      token: ${{ steps.app.outputs.token }}
    steps:
      - uses: actions/create-github-app-token@v2
        id: app
        with:
          app-id: ${{ vars.DOCS_SYNC_APP_ID }}
          private-key: ${{ secrets.DOCS_SYNC_APP_PRIVATE_KEY }}
          owner: docker
          repositories: docs

  # On PR — validate that docs still build (existing workflow, unchanged)
  validate:
    needs: docs-yaml
    uses: docker/docs/.github/workflows/validate-upstream.yml@main
    with:
      module-name: docker/buildx
      data-files-id: cli-yaml
      data-files-folder: buildx

  # On release — sync to docker/docs (new workflow)
  sync:
    needs: [docs-yaml, token]
    uses: docker/docs/.github/workflows/sync-upstream-cli.yml@main
    with:
      data-files-id: cli-yaml
      data-files-folder: buildx
      version: ${{ github.ref_name }}
    secrets:
      token: ${{ needs.token.outputs.token }}

The data-files-id and data-files-folder inputs are shared between both workflows. The only differences:

• validate adds module-name (for Hugo module replacement of markdown content)
• sync adds version + token (for commit metadata and write access)

The sync workflow:

1. Downloads the YAML artifact
2. Replaces data/cli/<folder>/*.yaml (clear + copy, so deletions are reflected)
3. Opens/updates a PR in docker/docs

Migration plan

Adoption is incremental — each upstream migrates when ready:

Repo	Current mechanism	Migration
docker/buildx	Semi-manual alongside vendor	Add sync call to existing docs-release.yml
docker/compose	Hugo module mount	Add docs-release.yml with sync call, remove mount from hugo.yaml
docker/model-runner	Hugo module mount	Same
docker/cli	Daily cron (sync-cli-docs.sh)	Add docs-release.yml triggered on tag push, retire cron + script
scout, mcp, desktop, etc.	Manual commits	Add workflow when ready; manual still works in the meantime

What this does NOT change

• Hugo module imports for markdown content (buildkit Dockerfile ref, bake docs, deprecated.md, etc.) stay as-is. Those are a separate concern.
• validate-upstream.yml stays — it validates upstream PRs before merge. This new workflow syncs after release. They're complementary.
• The _content.gotmpl content adapter stays — it already generates CLI pages from whatever YAML is in data/cli/.

Cleanup opportunities

• validate-upstream.yml still has a create-placeholder-stubs input that is no longer needed since the content adapter generates pages dynamically. Can be removed in a follow-up.
• Once all CLI tools use the sync workflow, sync-cli-docs.yml and hack/sync-cli-docs.sh can be retired.

Setup

1. Create a GitHub App (docker-docs-sync) in the Docker org with contents:write + pull-requests:write
2. Install it on docker/docs
3. Store App ID as org variable (DOCS_SYNC_APP_ID) and private key as org secret (DOCS_SYNC_APP_PRIVATE_KEY), accessible to upstream repos

---

This is an RFC — feedback welcome before we start migrating upstream repos.

[netlify]

✅ Deploy Preview for docsdocker ready!

Name	Link
🔨 Latest commit	c0a799b
🔍 Latest deploy log	https://app.netlify.com/projects/docsdocker/deploys/69df94f2cb4e7c00087190f0
😎 Deploy Preview	https://deploy-preview-24736--docsdocker.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[dvdksn]

Superseded by #24739 — flipped from push model (workflow_call from upstream) to pull model (docker/docs pulls via bake git context). No cross-repo auth needed.