ci(docs): deploy site only on stable APM releases (#822)

* Initial plan

* 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>

* 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>

* 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>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>

Author: Copilot

.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

CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Docs site publishes on stable release only, not every push to `main`. Closes #641 (#822)
+
 ## [0.9.0] - 2026-04-21
 
 ### Changed (BREAKING)