pulumi-cloud-sdk-java-docs.yml

permissions: write-all # Equivalent to default permissions + id-token: write
env:
  ESC_ACTION_OIDC_AUTH: true
  ESC_ACTION_OIDC_ORGANIZATION: pulumi
  ESC_ACTION_OIDC_REQUESTED_TOKEN_TYPE: urn:pulumi:token-type:access_token:organization
  ESC_ACTION_ENVIRONMENT: github-secrets/pulumi-docs
  ESC_ACTION_EXPORT_ENVIRONMENT_VARIABLES: GITHUB_TOKEN=PULUMI_BOT_TOKEN

name: Pulumi Cloud SDK docs - Java
on:
  workflow_dispatch:
    inputs:
      version:
        description: "com.pulumi:pulumi-cloud-sdk version (e.g. 2026.10.9, with or without leading 'v')"
        required: true
      skip_auto_merge:
        description: "Skip enabling auto-merge on the generated PR (for testing)"
        type: boolean
        default: false
      publish_only:
        description: "Generate + publish the versioned snapshot only; skip the latest-docs PR (for backfill)"
        type: boolean
        default: false
      target_env:
        description: "Versioned-docs publish target (when publishing)"
        type: choice
        options:
          - production
          - testing
        default: production

jobs:
  pull-request:
    runs-on: ubuntu-latest
    needs: build-pulumi-cloud-sdk-java-docs
    if: needs.build-pulumi-cloud-sdk-java-docs.outputs.has_changes == 'true' && github.event.inputs.publish_only != 'true'
    steps:
      - name: Fetch secrets from ESC
        id: esc-secrets
        uses: pulumi/esc-action@v3
      - name: checkout docs repo
        uses: actions/checkout@v7
      - name: set the cloud sdk version
        env:
          RAW_VERSION: ${{ github.event.inputs.version || github.event.client_payload.ref }}
        run: |
          echo "CLOUD_SDK_VERSION=${RAW_VERSION#v}" >> $GITHUB_ENV
      - name: pull-request
        id: create-pr
        uses: repo-sync/pull-request@v2
        with:
          source_branch: "pulumi-cloud-sdk-java-docs/${{ github.run_id }}-${{ github.run_number }}"
          destination_branch: "master"
          pr_title: "Generate Pulumi Cloud SDK docs - Java @v${{ env.CLOUD_SDK_VERSION }}"
          pr_body: |
            Automated PR generated by the [Pulumi Cloud SDK docs - Java](https://github.com/${{ github.repository }}/blob/master/.github/workflows/pulumi-cloud-sdk-java-docs.yml) workflow (`.github/workflows/pulumi-cloud-sdk-java-docs.yml`).

            Workflow run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
          pr_label: "automation/pulumi-cloud-sdk-java-docs,automation/merge"
          github_token: ${{ steps.esc-secrets.outputs.PULUMI_BOT_TOKEN }}
      - name: Enable auto-merge
        if: steps.create-pr.outputs.pr_created == 'true' && github.event.inputs.skip_auto_merge != 'true'
        run: gh pr merge ${{ steps.create-pr.outputs.pr_number }} --auto --squash
        env:
          GITHUB_TOKEN: ${{ steps.esc-secrets.outputs.PULUMI_BOT_TOKEN }}
  build-pulumi-cloud-sdk-java-docs:
    runs-on: ubuntu-latest
    outputs:
      has_changes: ${{ steps.commit.outputs.has_changes }}
    steps:
      - name: Fetch secrets from ESC
        id: esc-secrets
        uses: pulumi/esc-action@v3
      - name: set the cloud sdk version
        env:
          RAW_VERSION: ${{ github.event.inputs.version || github.event.client_payload.ref }}
        run: |
          echo "CLOUD_SDK_VERSION=${RAW_VERSION#v}" >> $GITHUB_ENV
      - name: resolve the cloud sdk release tag
        # pulumi-cloud-sdk tags releases v<YYYY-MM-DD>--<HHMM> and publishes the day's first
        # tag as <Y>.<M>.<D> and any later same-day tag as <Y>.<M>.<D>-post<HHMM> (see its
        # release.yml), so the tag is recoverable from the package version alone.
        run: |
          base="${CLOUD_SDK_VERSION%%-post*}"
          IFS=. read -r y m d <<< "$base"
          date="$(printf '%04d-%02d-%02d' "$y" "$m" "$d")"
          if [[ "$CLOUD_SDK_VERSION" == *-post* ]]; then
            tag="v${date}--${CLOUD_SDK_VERSION##*-post}"
          else
            tag="$(git ls-remote --tags --refs https://github.com/pulumi/pulumi-cloud-sdk "refs/tags/v${date}--*" | sed 's#.*refs/tags/##' | sort | head -1)"
          fi
          if [ -z "$tag" ]; then
            echo "::error::no pulumi-cloud-sdk release tag found for version ${CLOUD_SDK_VERSION}"
            exit 1
          fi
          echo "CLOUD_SDK_TAG=${tag}" >> "$GITHUB_ENV"
      - name: checkout docs repo
        uses: actions/checkout@v7
        with:
          path: docs
      - name: checkout pulumi-cloud-sdk repo
        uses: actions/checkout@v7
        with:
          repository: pulumi/pulumi-cloud-sdk
          path: pulumi-cloud-sdk
          ref: ${{ env.CLOUD_SDK_TAG }}
      - name: Install Java
        uses: actions/setup-java@v6.0.1
        with:
          java-version: '17'
          distribution: temurin
      - name: Install Hugo (version pinned in mise.toml)
        uses: ./docs/.github/actions/setup-hugo
      - name: Install node
        uses: actions/setup-node@v7
        with:
          node-version: '24.x'
          cache: 'yarn'
          cache-dependency-path: |
            docs/yarn.lock
            docs/infrastructure/yarn.lock
            docs/theme/yarn.lock
            docs/theme/stencil/yarn.lock
      - name: Install Vale (required by scripts/ensure.sh)
        run: |
          VALE_VERSION="3.14.1"
          VALE_SHA256="ff2b49ffaa9dcd246fd5008f03ff67746d2790b75bf4d3657e2fb9530fb96db3"
          curl -fsSL --retry 3 --retry-all-errors --retry-delay 5 \
            --retry-max-time 300 --connect-timeout 10 --max-time 120 \
            -o /tmp/vale.tar.gz "https://github.com/errata-ai/vale/releases/download/v${VALE_VERSION}/vale_${VALE_VERSION}_Linux_64-bit.tar.gz"
          echo "${VALE_SHA256}  /tmp/vale.tar.gz" | sha256sum -c -
          sudo tar -xz -C /usr/local/bin vale -f /tmp/vale.tar.gz
          rm /tmp/vale.tar.gz
      - run: make ensure
        working-directory: docs
      - name: Generate Cloud SDK Java docs
        run: ./scripts/gen_javadoc.sh
        working-directory: docs
        env:
          JAVA_REPO: ${{ github.workspace }}/pulumi-cloud-sdk
          JAVA_SDK_VERSION: ${{ env.CLOUD_SDK_VERSION }}
          JAVADOC_PROJECT_DIR: ${{ github.workspace }}/pulumi-cloud-sdk/java
          JAVADOC_SRC: ${{ github.workspace }}/pulumi-cloud-sdk/java/build/docs/javadoc
          JAVADOC_DEST: ./static-prebuilt/docs/reference/pkg/java/cloud-sdk
          JAVADOC_GRADLE: ./gradlew --console=plain
          JAVADOC_PRESERVE: ""
          JAVADOC_SDK_NAME: Pulumi Cloud Java SDK
          JAVADOC_LIBRARY: com.pulumi.cloud.sdk
          JAVADOC_REPOSITORY: https://github.com/pulumi/pulumi-cloud-sdk
          JAVADOC_PACKAGE_BLURB: ", a client for the Pulumi Cloud REST API"
      - name: git status
        run: git status && git diff
        working-directory: docs
      - name: commit changes
        id: commit
        run: |
          git config --local user.email "bot@pulumi.com"
          git config --local user.name "pulumi-bot"
          git checkout -b pulumi-cloud-sdk-java-docs/${{ github.run_id }}-${{ github.run_number }}
          git add static-prebuilt/
          if git diff --cached --quiet; then
            echo "No changes to commit"
            echo "has_changes=false" >> $GITHUB_OUTPUT
          else
            git commit -m "Regenerating Pulumi Cloud SDK Java docs for pulumi-cloud-sdk@${{ env.CLOUD_SDK_VERSION }}"
            if [ "${{ github.event.inputs.publish_only }}" != "true" ]; then
              git push origin pulumi-cloud-sdk-java-docs/${{ github.run_id }}-${{ github.run_number }}
            fi
            echo "has_changes=true" >> $GITHUB_OUTPUT
          fi
        working-directory: docs
      # --- Versioned docs: archive this SDK release as an immutable snapshot. ---------
      # No enable flag: the publish turns itself on once the versioned-docs storage stack
      # exists - the resolve step reads the bucket/role/distribution from stack outputs and
      # every step below no-ops while they are absent. Runs after commit, continue-on-error,
      # so a publish hiccup never blocks the docs PR.
      - name: Resolve versioned-docs publish target
        id: vdocs
        env:
          PULUMI_ACCESS_TOKEN: ${{ steps.esc-secrets.outputs.PULUMI_ACCESS_TOKEN }}
        run: |
          TARGET="${{ github.event.inputs.target_env || 'production' }}"
          if [ "$TARGET" = "testing" ]; then
            STORAGE_STACK="pulumi/pulumi-docs-versioned/testing"
            WWW_STACK="pulumi/www.pulumi.com/www-testing"
            SITE="https://www.pulumi-test.io"
          else
            STORAGE_STACK="pulumi/pulumi-docs-versioned/production"
            WWW_STACK="pulumi/www.pulumi.com/www-production"
            SITE="https://www.pulumi.com"
          fi
          # Resolve EVERYTHING from the IaC that owns it - no hardcoded names, no enable flag.
          # The bucket + publisher role come from the versioned-docs storage stack; the
          # CloudFront distribution (for the post-publish invalidation) from the www stack.
          # An empty bucket means versioned docs are not stood up for this env yet: every step
          # below is gated on bucket != '' and simply no-ops, so the feature turns itself on
          # the moment the storage stack exists. Mirrors how scripts/run-pulumi.sh and the
          # registry repo read these values from stack outputs instead of copying them.
          BUCKET="$(pulumi stack output bucketNameOutput --stack "$STORAGE_STACK" 2>/dev/null || true)"
          ROLE_ARN="$(pulumi stack output publisherRoleArn --stack "$STORAGE_STACK" 2>/dev/null || true)"
          DIST_ID="$(pulumi stack output cloudFrontDistributionId --stack "$WWW_STACK" 2>/dev/null || true)"
          if [ -z "$BUCKET" ]; then
            echo "::notice::versioned-docs: storage stack $STORAGE_STACK has no bucket output - versioned docs are not stood up for '$TARGET'; skipping the archive publish."
          elif [ -z "$DIST_ID" ]; then
            echo "::warning::versioned-docs: could not read cloudFrontDistributionId from $WWW_STACK; publishing without a CloudFront invalidation (staleness bounded by the 300s manifest TTL)."
          fi
          {
            echo "role_arn=$ROLE_ARN"
            echo "bucket=$BUCKET"
            echo "distribution_id=$DIST_ID"
            echo "site=$SITE"
          } >> "$GITHUB_OUTPUT"
      - name: Configure AWS credentials (versioned-docs publisher)
        if: ${{ steps.vdocs.outputs.bucket != '' }}
        continue-on-error: true
        uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: ${{ steps.vdocs.outputs.role_arn }}
          role-session-name: versioned-docs-sdk-publish
          aws-region: us-west-2
      - name: Publish versioned snapshot
        if: ${{ steps.vdocs.outputs.bucket != '' }}
        continue-on-error: true
        working-directory: docs
        run: |
          # Backfill (publish_only) archives an OLD release: do not mark it "latest".
          EXTRA=()
          [ "${{ github.event.inputs.publish_only }}" = "true" ] && EXTRA+=(--no-mark-latest)
          ./scripts/versioned-docs/publish-version.sh --tool java-cloud-sdk \
            --version "v${{ env.CLOUD_SDK_VERSION }}" \
            --src static-prebuilt/docs/reference/pkg/java/cloud-sdk \
            --live-root /docs/reference/pkg/java/cloud-sdk/ \
            --bucket "${{ steps.vdocs.outputs.bucket }}" --label "Cloud SDK (Java)" \
            --distribution-id "${{ steps.vdocs.outputs.distribution_id }}" \
            --site "${{ steps.vdocs.outputs.site }}" \
            "${EXTRA[@]}"
  notify:
    if: failure() && github.event.inputs.publish_only != 'true'
    name: Send slack notification
    runs-on: ubuntu-latest
    needs: [pull-request, build-pulumi-cloud-sdk-java-docs]
    steps:
      - name: Fetch secrets from ESC
        id: esc-secrets
        uses: pulumi/esc-action@v3
      - name: Slack Notification
        uses: docker://sholung/action-slack-notify:v2.3.0
        env:
          SLACK_CHANNEL: docs-ops
          SLACK_COLOR: "#F54242"
          SLACK_MESSAGE: "Pulumi Cloud SDK docs - Java build failure in pulumi/docs repo"
          SLACK_USERNAME: docsbot
          SLACK_WEBHOOK: ${{ steps.esc-secrets.outputs.SLACK_WEBHOOK_URL }}
          SLACK_ICON: https://www.pulumi.com/logos/brand/avatar-on-white.png