publish-docs.yaml

# yaml-language-server: $schema=https://www.schemastore.org/github-workflow.json
---
name: Generate reference docs

on:
  workflow_dispatch:
    inputs:
      open_pull_request:
        description: |
          Open a pull request against the docs repository. Defaults to false for a "dry run" of the workflow that generates the docs and uploads them as artifacts.
        required: false
        default: "false"
        type: choice
        options:
          - "true"
          - "false"
  push:
    branches:
      - main
      - release/*
  pull_request:
    branches:
      - main

permissions: {}

jobs:
  changes:
    name: Changes
    uses: ./.github/workflows/__changes.yml
    permissions:
      contents: read
      pull-requests: read

  reference-docs:
    name: Generate and PR reference documentation
    if: github.repository == 'radius-project/radius' && needs.changes.outputs.only_changed != 'true'
    needs: [changes]
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    env:
      GOPRIVATE: github.com/radius-project
      # Only main may synchronize edge docs; release branches and PRs retain
      # their generated previews without writing to the docs repository.
      PUBLISH_DOCS: ${{ github.ref == 'refs/heads/main' && (github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.event.inputs.open_pull_request == 'true')) }}
    permissions:
      contents: read
    steps:
      - name: Checkout radius repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          repository: radius-project/radius
          path: radius
          persist-credentials: false

      - name: Parse release version and set environment variables
        working-directory: radius
        run: bash ./.github/scripts/release-version.sh >>"${GITHUB_ENV}"

      - name: Generate docs release branch name
        run: |
          if [[ "${REL_CHANNEL}" != "edge" ]]; then
            echo "DOCS_BRANCH=v${REL_CHANNEL}" >> "$GITHUB_ENV"
          else
            echo "DOCS_BRANCH=edge" >> "$GITHUB_ENV"
          fi

      - name: Checkout docs repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          repository: radius-project/docs
          path: docs
          ref: ${{ env.DOCS_BRANCH }}
          persist-credentials: false

      # Setup dependencies
      - name: Setup Go
        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
        with:
          go-version-file: radius/go.mod
          cache-dependency-path: radius/go.sum
          cache: false

      - name: Download Go modules
        uses: ./radius/.github/actions/go-mod-download
        with:
          working-directory: radius

      - name: Setup NodeJS
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version-file: radius/.node-version
          # This workflow publishes generated docs, so never restore a cache that a
          # prior workflow run could have poisoned.
          package-manager-cache: false

      - name: Install yq
        # Required by make generate-bicep-types-contrib to parse defaults.yaml.
        run: make install-yq
        working-directory: radius

      # Generate Bicep docs
      - name: Generate Bicep docs
        run: make generate
        working-directory: radius

      # Generate resource reference docs
      - name: Generate resource reference docs
        run: python docs/.github/scripts/generate_resource_references.py ./radius/hack/bicep-types-radius/generated/ ./docs/docs/content/reference/resources

      - name: Upload resource reference docs
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: resource-docs
          path: docs/docs/content/reference/resources

      # Generate and upload CLI docs
      - name: Generate CLI docs
        run: |
          find docs/docs/content/reference/cli -type f ! -name '_index.md' -delete
          cd radius
          go run cmd/docgen/main.go ../docs/docs/content/reference/cli

      - name: Upload CLI docs
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: cli-docs
          path: docs/docs/content/reference/cli

      # Open PR against docs repository
      - name: Show git diff
        run: |
          cd docs
          git status --porcelain -unormal -- *.md

      # Generate a short-lived GitHub App installation token scoped to the docs
      # repository. Tokens expire after one hour, are least-privilege (contents + pull-requests on docs only),
      # and let repo-files-sync create GPG-verified commits via the GitHub API.
      #
      # Requires the App's credentials to be configured on radius-project/radius:
      #   - secrets.RADIUS_DOCS_BOT_CLIENT_ID
      #   - secrets.RADIUS_DOCS_BOT_PRIVATE_KEY
      # and the App installed on radius-project/docs with contents + PR write access.
      - name: Generate GitHub App token
        id: app-token
        if: env.PUBLISH_DOCS == 'true'
        uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
        with:
          client-id: ${{ secrets.RADIUS_DOCS_BOT_CLIENT_ID }}
          private-key: ${{ secrets.RADIUS_DOCS_BOT_PRIVATE_KEY }}
          repositories: docs
          permission-contents: write
          permission-pull-requests: write

      # Resolve the App bot's GitHub-formatted name and email (e.g.
      # "<app-slug>[bot] <id+<app-slug>[bot]@users.noreply.github.com>") so commits
      # and the DCO sign-off are attributed correctly to the bot identity.
      - name: Get bot details
        id: bot-details
        if: env.PUBLISH_DOCS == 'true'
        uses: raven-actions/bot-details@ee8966a9ff6e7e42cbfc4a56b4ddb60a9d1b40a6 # v1.2.0
        with:
          bot-slug-name: ${{ steps.app-token.outputs.app-slug }}

      # Sync the generated reference docs to the radius-project/docs repository.
      #
      # Unlike the previous create-pull-request step (which cut a brand-new branch
      # named reference-cli/patch-<sha> on every run and quickly piled up dozens of
      # open PRs), repo-files-sync reuses a single, stable head branch per docs
      # branch: "<BRANCH_PREFIX>/<DOCS_BRANCH>". With OVERWRITE_EXISTING_PR enabled
      # it force-updates that branch and keeps exactly one open PR per docs branch,
      # amending it in place on subsequent runs.
      #
      # Only main pushes and opted-in main manual runs open a PR. Other refs
      # still generate and upload the docs as artifacts above for inspection.
      - name: Sync reference docs to docs repository
        if: env.PUBLISH_DOCS == 'true'
        uses: raven-actions/repo-files-sync@511c602835ac7dd8529673f91afe348db8d08185 # v0.1.0-rc.18
        with:
          # The App installation token authenticates as <app-slug>[bot]. Passing it as
          # GH_TOKEN makes repo-files-sync create verified commits through
          # the GitHub API and use the x-access-token git transport.
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          OVERWRITE_EXISTING_PR: true
          REBASE: true
          BRANCH_PREFIX: reference-docs
          # Installation tokens cannot resolve the committer via the API, so the bot
          # identity is supplied explicitly from the bot-details outputs.
          GIT_USERNAME: ${{ steps.bot-details.outputs.name }}
          GIT_EMAIL: ${{ steps.bot-details.outputs.email }}
          # repo-files-sync reuses one PR per docs branch and overwrites it on
          # each run, so a stable, descriptive title is preferable. Manual
          # (workflow_dispatch) runs are flagged so they are easy to spot.
          PR_TITLE: >-
            ${{ github.event_name == 'workflow_dispatch'
            && 'Update auto-generated reference documentation (manual trigger)'
            || format('Update auto-generated reference documentation ({0})', github.ref_name) }}
          # The action already prepends "synced local file(s) with <repo>.", lists
          # the changed files, and appends a footer linking the source workflow
          # run, so the body only needs a direct link to the triggering commit.
          PR_BODY: "Auto-generated from [radius-project/radius@${{ github.sha }}](${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }})."
          PR_LABELS: documentation
          COMMIT_PREFIX: "docs:"
          # Preserve the DCO sign-off the previous step added via `signoff: true`.
          # COMMIT_BODY is appended to the commit message, so the Signed-off-by trailer
          # (formatted by bot-details) satisfies the docs repository's DCO check.
          COMMIT_BODY: "Signed-off-by: ${{ steps.bot-details.outputs.name-email }}"
          # The docs repo is checked out at ./docs, so the generated files live under
          # docs/docs/content/reference/... and map to docs/content/reference/... in
          # the target repo. The PR base branch is taken from "@<DOCS_BRANCH>".
          # deleteOrphaned keeps the target in sync when generated files are removed
          # (e.g. CLI docs are regenerated from scratch, preserving only _index.md).
          INLINE_CONFIG: |
            radius-project/docs@${{ env.DOCS_BRANCH }}:
              - source: docs/docs/content/reference/resources/
                dest: docs/content/reference/resources/
                deleteOrphaned: true
              - source: docs/docs/content/reference/cli/
                dest: docs/content/reference/cli/
                deleteOrphaned: true