From 7e24bfbfb92123e77b823e329e6fe7abc883cdd8 Mon Sep 17 00:00:00 2001
From: danielmeppiel <dmeppiel@microsoft.com>
Date: Sun, 26 Apr 2026 15:52:27 +0200
Subject: [PATCH] fix(ci): deploy docs after bot-cut releases via workflow_call

Releases created by GITHUB_TOKEN do not trigger downstream workflow
runs (a documented Actions safeguard against recursion), so the
`release: published` trigger on docs.yml never fired for v0.9.3 --
which is why https://microsoft.github.io/apm still serves pre-0.9.3
content even though the v0.9.3 release published successfully.

Fix: convert docs.yml into a reusable workflow (`workflow_call` with
an `is_prerelease` input) and have the CI/CD Pipeline's release job
invoke it directly via a new `deploy-docs` job after `create-release`.

This is the cleanest fix under Microsoft org policy:

- No new credentials. A PAT or GitHub App token would also work
  (release would then be attributed to a non-bot identity, so
  `release: published` would fire), but App installs on Microsoft-org
  repos require security review, and PATs are tied to a user and have
  rotation/policy overhead.
- No `workflow_run` gotchas. `workflow_run` would tightly couple
  docs.yml to the CI/CD Pipeline name, always run the default-branch
  workflow file (cut-at-tag pinning gotcha), and force docs.yml to
  re-derive whether the upstream run actually cut a release.
- Backward compatible. `release: published` and `workflow_dispatch`
  triggers are kept, so human-cut releases and manual re-publishes
  continue to work unchanged.
- Visible in the Actions DAG. The deploy appears as a child of the
  release run, so 'did docs deploy?' is one click from the release
  run instead of buried in a separate workflow timeline.

For v0.9.3 specifically, the docs site can be republished via a
manual `Deploy Docs` workflow_dispatch run on `main`.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/workflows/build-release.yml | 18 ++++++++++++++++++
 .github/workflows/docs.yml          | 21 +++++++++++++++++----
 2 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/build-release.yml b/.github/workflows/build-release.yml
index e41dd6600..c80f9b587 100644
--- a/.github/workflows/build-release.yml
+++ b/.github/workflows/build-release.yml
@@ -627,6 +627,24 @@ jobs:
             ./dist/apm-windows-x86_64.zip
             ./dist/apm-windows-x86_64.zip.sha256
 
+  # Deploy the docs site after the release is published.
+  # Invoked here (rather than via the docs workflow's `release: published`
+  # trigger) because release events created by GITHUB_TOKEN do not fire
+  # downstream workflow runs -- a documented Actions safeguard against
+  # recursion. Calling docs.yml directly preserves the standard release ->
+  # docs deploy chain without needing a PAT or GitHub App token.
+  deploy-docs:
+    name: Deploy Docs
+    needs: [create-release]
+    if: github.ref_type == 'tag' && needs.create-release.outputs.is_prerelease != 'true'
+    uses: ./.github/workflows/docs.yml
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    with:
+      is_prerelease: false
+
   # GH-AW Compatibility — validates the released binary works in the
   # exact flow GitHub Agentic Workflows uses (isolated install + pack, no token).
   # Informational: runs as continue-on-error because it depends on external services
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index fd3670cfa..935c0b431 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -3,8 +3,19 @@ name: Deploy Docs
 on:
   # Deploy docs only when a new APM version is released, so the published
   # site always matches the latest released binary (see microsoft/apm#641).
-  # PR runs build (no deploy) to catch breakage before merge. Manual
-  # workflow_dispatch is supported for re-publishing the current docs.
+  # Primary entrypoint is workflow_call from the CI/CD Pipeline release job
+  # (release: published does not fire when the release is created by
+  # GITHUB_TOKEN -- a documented Actions safeguard against recursion).
+  # The release: published trigger is kept as a safety net for human-cut
+  # releases. PR runs build (no deploy) to catch breakage before merge.
+  # Manual workflow_dispatch is supported for re-publishing the current docs.
+  workflow_call:
+    inputs:
+      is_prerelease:
+        description: 'Skip deploy when true (build-only). Defaults to false (deploy).'
+        required: false
+        type: boolean
+        default: false
   release:
     types: [published]
   pull_request:
@@ -45,7 +56,8 @@ jobs:
       - name: Upload build artifacts
         if: |
           github.event_name == 'workflow_dispatch' ||
-          (github.event_name == 'release' && github.event.release.prerelease == false)
+          (github.event_name == 'release' && github.event.release.prerelease == false) ||
+          (github.event_name == 'workflow_call' && inputs.is_prerelease == false)
         uses: actions/upload-pages-artifact@v3
         with:
           path: docs/dist
@@ -56,7 +68,8 @@ jobs:
     # so prerelease tags (vX.Y.Z-rc1, etc.) don't clobber published docs.
     if: |
       github.event_name == 'workflow_dispatch' ||
-      (github.event_name == 'release' && github.event.release.prerelease == false)
+      (github.event_name == 'release' && github.event.release.prerelease == false) ||
+      (github.event_name == 'workflow_call' && inputs.is_prerelease == false)
     runs-on: ubuntu-latest
     permissions:
       pages: write