Route published docs through pull requests (#4713)

.github/workflows/publish-fastmcp.yml

@@ -178,19 +178,27 @@ jobs:
         run: uv publish -v dist/fastmcp-*.tar.gz dist/fastmcp-*.whl
 
   update-published-docs:
-    name: Update published-docs branch
+    name: Open published-docs PR
     runs-on: ubuntu-latest
     needs: pypi-publish
     if: github.event_name == 'workflow_run' && github.event.workflow_run.event == 'release' && needs['pypi-publish'].outputs.is_prerelease != 'true'
-    timeout-minutes: 2
+    timeout-minutes: 5
     permissions:
-      contents: write
+      contents: read
 
     steps:
+      - name: Generate Marvin App token
+        id: marvin-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.MARVIN_APP_ID }}
+          private-key: ${{ secrets.MARVIN_APP_PRIVATE_KEY }}
+
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
           ref: ${{ github.event.workflow_run.head_sha }}
+          token: ${{ steps.marvin-token.outputs.token }}
 
       - name: Check release line
         id: release_line
@@ -205,6 +213,26 @@ jobs:
             echo "Release commit is not on ${DEFAULT_BRANCH}; skipping published-docs update."
           fi
 
-      - name: Point published-docs at published release
+      - name: Prepare published docs tree
         if: steps.release_line.outputs.update_published_docs == 'true'
-        run: git push --force origin "HEAD:published-docs"
+        env:
+          RELEASE_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          git fetch origin published-docs
+          git switch --force-create published-docs-sync origin/published-docs
+          git read-tree --reset -u "$RELEASE_SHA"
+          test "$(git write-tree)" = "$(git rev-parse "${RELEASE_SHA}^{tree}")"
+
+      - name: Open published docs PR
+        if: steps.release_line.outputs.update_published_docs == 'true'
+        uses: peter-evans/create-pull-request@v8
+        with:
+          token: ${{ steps.marvin-token.outputs.token }}
+          base: published-docs
+          branch: marvin/publish-docs-v${{ needs.pypi-publish.outputs.version }}
+          commit-message: "Publish FastMCP v${{ needs.pypi-publish.outputs.version }} docs"
+          title: "Publish FastMCP v${{ needs.pypi-publish.outputs.version }} docs"
+          body: "Updates `published-docs` to the exact release tree. Merging publishes the documentation to production."
+          delete-branch: true
+          author: "marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com>"
+          committer: "marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com>"