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 3c3ed2c30..eb4a6252d 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
+
+- Docs site publishes on stable release only, not every push to `main`. Closes #641 (#822)
+
 ## [0.9.0] - 2026-04-21
 
 ### Changed (BREAKING)