From 2ba67840e2e272302e79e4c88cf9aad10f68412b Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 21 Apr 2026 19:33:51 +0000
Subject: [PATCH 1/4] Initial plan


From 6749af3b2cfb86ecafafcca1efa2375d53c11595 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 21 Apr 2026 19:35:43 +0000
Subject: [PATCH 2/4] ci(docs): deploy site only on stable APM releases

Agent-Logs-Url: https://github.com/microsoft/apm/sessions/14d49930-6ded-446d-826b-2e9de5fd314c

Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
---
 .github/workflows/docs.yml | 19 ++++++++++++++-----
 CHANGELOG.md               |  4 ++++
 2 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 8d37ab72f..fd3670cfa 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -1,9 +1,12 @@
 name: Deploy Docs
 
 on:
-  push:
-    branches: [main]
-    paths: ['docs/**']
+  # 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.
+  release:
+    types: [published]
   pull_request:
     paths: ['docs/**']
   workflow_dispatch:
@@ -40,14 +43,20 @@ jobs:
         run: npm run build
 
       - name: Upload build artifacts
-        if: github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch'
+        if: |
+          github.event_name == 'workflow_dispatch' ||
+          (github.event_name == 'release' && github.event.release.prerelease == false)
         uses: actions/upload-pages-artifact@v3
         with:
           path: docs/dist
 
   deploy:
     needs: build
-    if: github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch'
+    # Only stable releases (or manual dispatch) update the public docs site,
+    # 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)
     runs-on: ubuntu-latest
     permissions:
       pages: write
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1c237ea93..2e6752630 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Documentation site is now deployed only when a new APM version is released (GitHub release `published` event), instead of on every push to `main`. PR builds still run for validation but no longer publish, eliminating the window where docs referenced features not yet in the latest released binary. Prerelease tags do not update the public site; manual `workflow_dispatch` is still supported for re-publishing. Closes #641
+
 ## [0.9.0] - 2026-04-21
 
 ### Changed (BREAKING)

From f98d6f51d232ea92abfb8c171f34a58cec045180 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 21 Apr 2026 20:03:16 +0000
Subject: [PATCH 3/4] docs(changelog): shorten docs-deploy entry

Agent-Logs-Url: https://github.com/microsoft/apm/sessions/e78aeb70-fef5-4b54-bb13-71921966c605

Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0ca394139..6981828aa 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- Documentation site is now deployed only when a new APM version is released (GitHub release `published` event), instead of on every push to `main`. PR builds still run for validation but no longer publish, eliminating the window where docs referenced features not yet in the latest released binary. Prerelease tags do not update the public site; manual `workflow_dispatch` is still supported for re-publishing. Closes #641
+- Docs site now publishes on stable release only, not every push to `main`. Closes #641
 
 ## [0.9.0] - 2026-04-21
 

From cebf2eedca140965a94acdfea8c26849d08159e5 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Tue, 21 Apr 2026 20:05:27 +0000
Subject: [PATCH 4/4] docs(changelog): add PR number to docs-deploy entry

Agent-Logs-Url: https://github.com/microsoft/apm/sessions/a3f48c9c-db2c-45b8-a2aa-ccef51a5561f

Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6981828aa..eb4a6252d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- Docs site now publishes on stable release only, not every push to `main`. Closes #641
+- Docs site publishes on stable release only, not every push to `main`. Closes #641 (#822)
 
 ## [0.9.0] - 2026-04-21