From dd9eb9dd3bd28db7f318000ac6731ce8f8818691 Mon Sep 17 00:00:00 2001 From: Den Delimarsky Date: Tue, 30 Jun 2026 07:55:18 +0000 Subject: [PATCH 1/3] Add Cloudflare Pages docs preview workflow with /preview-docs slash command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PRs from repo admins that touch docs auto-deploy a mkdocs preview to Cloudflare Pages; for everyone else, an admin or maintainer can comment `/preview-docs` to trigger one. A sticky PR comment carries the preview link, and a companion workflow deletes the deployments when the PR closes. Because mkdocs executes Python from the PR (mkdocstrings imports src/mcp), the build is gated by a permission check on the triggering actor and runs in a separate job with no secrets — the static site is handed to the Cloudflare deploy step via an artifact so PR code never shares a runner with the API token. The pull_request_target trigger is suppressed in zizmor with this rationale. :house: Remote-Dev: homespace --- .github/workflows/docs-preview-cleanup.yml | 44 +++++ .github/workflows/docs-preview.yml | 219 +++++++++++++++++++++ .github/zizmor.yml | 10 + 3 files changed, 273 insertions(+) create mode 100644 .github/workflows/docs-preview-cleanup.yml create mode 100644 .github/workflows/docs-preview.yml create mode 100644 .github/zizmor.yml diff --git a/.github/workflows/docs-preview-cleanup.yml b/.github/workflows/docs-preview-cleanup.yml new file mode 100644 index 000000000..3e1cd70f1 --- /dev/null +++ b/.github/workflows/docs-preview-cleanup.yml @@ -0,0 +1,44 @@ +name: Docs Preview Cleanup + +# Deletes Cloudflare Pages preview deployments for a PR when it closes. +# Runs as pull_request_target so secrets are available for fork PRs; it never +# checks out PR code, so there is no untrusted-code execution risk. + +on: + pull_request_target: + types: [closed] + +permissions: {} + +jobs: + cleanup: + runs-on: ubuntu-latest + steps: + - name: Delete preview deployments for this PR + env: + CF_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} + CF_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} + CF_PROJECT: ${{ vars.CLOUDFLARE_PAGES_PROJECT }} + BRANCH: pr-${{ github.event.pull_request.number }} + run: | + set -euo pipefail + if [ -z "$CF_API_TOKEN" ] || [ -z "$CF_ACCOUNT_ID" ] || [ -z "$CF_PROJECT" ]; then + echo "Cloudflare credentials/project not configured; skipping cleanup." + exit 0 + fi + base="https://api.cloudflare.com/client/v4/accounts/$CF_ACCOUNT_ID/pages/projects/$CF_PROJECT/deployments" + # Collect matching ids across all pages first, then delete — deleting + # mid-pagination would shift later pages and skip entries. + ids="" + for page in $(seq 1 50); do + resp=$(curl -fsS -H "Authorization: Bearer $CF_API_TOKEN" "$base?env=preview&per_page=25&page=$page") + ids="$ids $(jq -r --arg b "$BRANCH" '.result[]? | select(.deployment_trigger.metadata.branch == $b) | .id' <<<"$resp")" + [ "$(jq '.result | length' <<<"$resp")" -lt 25 ] && break + done + deleted=0 + for id in $ids; do + echo "Deleting deployment $id" + curl -fsS -X DELETE -H "Authorization: Bearer $CF_API_TOKEN" "$base/$id?force=true" > /dev/null + deleted=$((deleted + 1)) + done + echo "Deleted $deleted deployment(s) for $BRANCH." diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml new file mode 100644 index 000000000..8b78585f2 --- /dev/null +++ b/.github/workflows/docs-preview.yml @@ -0,0 +1,219 @@ +name: Docs Preview + +# Builds the mkdocs site for a PR and deploys it to Cloudflare Pages. +# +# Security: mkdocs executes Python from the PR (mkdocstrings imports src/mcp, +# `!!python/name:` directives). The build is gated by `authorize` (admin sender +# for auto-preview, admin/maintainer commenter for /preview-docs) and isolated +# from Cloudflare secrets — `build` runs PR code with no secrets and hands the +# static site to `deploy` via an artifact, so PR code never shares a runner +# with the Cloudflare token. +# +# Required configuration: +# - secrets.CLOUDFLARE_API_TOKEN (scope: Account → Cloudflare Pages → Edit) +# - secrets.CLOUDFLARE_ACCOUNT_ID +# - vars.CLOUDFLARE_PAGES_PROJECT (existing Pages project, e.g. mcp-python-sdk-docs) + +on: + pull_request_target: + types: [opened, reopened, synchronize] + paths: + - docs/** + - docs_src/** + - mkdocs.yml + - pyproject.toml + issue_comment: + types: [created] + +permissions: {} + +concurrency: + group: docs-preview-pr-${{ github.event.pull_request.number || github.event.issue.number }} + cancel-in-progress: true + +jobs: + authorize: + if: >- + github.event_name == 'pull_request_target' || + (github.event.issue.pull_request && startsWith(github.event.comment.body, '/preview-docs')) + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: read + outputs: + authorized: ${{ steps.check.outputs.authorized }} + pr_number: ${{ steps.check.outputs.pr_number }} + head_sha: ${{ steps.check.outputs.head_sha }} + slash_attempt: ${{ steps.check.outputs.slash_attempt }} + steps: + - name: Determine authorization + id: check + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + with: + script: | + const { owner, repo } = context.repo; + + async function permissionFor(username) { + const { data } = await github.rest.repos.getCollaboratorPermissionLevel({ owner, repo, username }); + return { level: data.permission, role: data.role_name }; + } + + let authorized = false; + let prNumber = ''; + let headSha = ''; + let slashAttempt = false; + + if (context.eventName === 'pull_request_target') { + // Gate on the *sender* (whoever caused this run — on synchronize that + // is the pusher), not the PR author, so a non-admin pushing to an + // admin-opened branch does not get an automatic build. + const actor = context.payload.sender.login; + prNumber = String(context.payload.pull_request.number); + headSha = context.payload.pull_request.head.sha; + const perm = await permissionFor(actor); + authorized = perm.level === 'admin'; + core.info(`pull_request_target by ${actor} (level=${perm.level}, role=${perm.role}) → authorized=${authorized}`); + } else { + // issue_comment: the job-level `if:` already guarantees this is a PR + // comment starting with /preview-docs. + slashAttempt = true; + const actor = context.payload.comment.user.login; + prNumber = String(context.payload.issue.number); + const perm = await permissionFor(actor); + authorized = perm.level === 'admin' || perm.role === 'maintain'; + if (authorized) { + const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: Number(prNumber) }); + if (pr.state !== 'open') { + authorized = false; + core.info(`PR #${prNumber} is ${pr.state}; refusing to preview.`); + } else { + headSha = pr.head.sha; + } + } + core.info(`/preview-docs by ${actor} (level=${perm.level}, role=${perm.role}) → authorized=${authorized}`); + } + + core.setOutput('authorized', String(authorized)); + core.setOutput('pr_number', prNumber); + core.setOutput('head_sha', headSha); + core.setOutput('slash_attempt', String(slashAttempt)); + + build: + needs: authorize + if: needs.authorize.outputs.authorized == 'true' + runs-on: ubuntu-latest + permissions: + contents: read + steps: + - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + with: + ref: ${{ needs.authorize.outputs.head_sha }} + persist-credentials: false + + - name: Install uv + uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0 + with: + enable-cache: true + version: 0.9.5 + + - run: uv sync --frozen --group docs + - run: uv run --frozen --no-sync mkdocs build + + - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 + with: + name: site + path: site/ + retention-days: 1 + + deploy: + needs: [authorize, build] + if: needs.authorize.outputs.authorized == 'true' + runs-on: ubuntu-latest + permissions: {} + outputs: + deployment_url: ${{ steps.wrangler.outputs.deployment-url }} + alias_url: ${{ steps.wrangler.outputs.pages-deployment-alias-url }} + steps: + - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: site + path: site + + - name: Deploy to Cloudflare Pages + id: wrangler + uses: cloudflare/wrangler-action@ebbaa1584979971c8614a24965b4405ff95890e0 # v4.0.0 + with: + apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} + accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} + packageManager: npm + command: >- + pages deploy ./site + --project-name=${{ vars.CLOUDFLARE_PAGES_PROJECT }} + --branch=pr-${{ needs.authorize.outputs.pr_number }} + --commit-hash=${{ needs.authorize.outputs.head_sha }} + --commit-dirty=true + + comment: + needs: [authorize, build, deploy] + if: >- + always() && + needs.deploy.result != 'cancelled' && + (needs.authorize.outputs.authorized == 'true' || needs.authorize.outputs.slash_attempt == 'true') + runs-on: ubuntu-latest + permissions: + pull-requests: write + steps: + - name: Post or update preview comment + uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0 + env: + AUTHORIZED: ${{ needs.authorize.outputs.authorized }} + PR_NUMBER: ${{ needs.authorize.outputs.pr_number }} + HEAD_SHA: ${{ needs.authorize.outputs.head_sha }} + DEPLOY_RESULT: ${{ needs.deploy.result }} + DEPLOYMENT_URL: ${{ needs.deploy.outputs.deployment_url }} + ALIAS_URL: ${{ needs.deploy.outputs.alias_url }} + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} + with: + script: | + const { owner, repo } = context.repo; + const env = process.env; + const issue_number = Number(env.PR_NUMBER); + const marker = ''; + + async function upsert(body) { + const comments = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number, per_page: 100 }); + const existing = comments.find(c => c.user?.type === 'Bot' && c.body?.includes(marker)); + if (existing) { + await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body }); + } else { + await github.rest.issues.createComment({ owner, repo, issue_number, body }); + } + } + + if (env.AUTHORIZED !== 'true') { + await github.rest.issues.createComment({ + owner, repo, issue_number, + body: `@${context.actor} — only repository admins or maintainers can run \`/preview-docs\` (and the PR must be open).`, + }); + return; + } + + if (env.DEPLOY_RESULT !== 'success') { + await upsert( + `${marker}\n### 📚 Documentation preview\n\n` + + `❌ Preview build **failed** for \`${env.HEAD_SHA.slice(0, 7)}\` — [workflow logs](${env.RUN_URL}).` + ); + return; + } + + const previewUrl = env.ALIAS_URL || env.DEPLOYMENT_URL; + const ts = new Date().toISOString().replace('T', ' ').replace(/\.\d+Z$/, ' UTC'); + await upsert( + `${marker}\n### 📚 Documentation preview\n\n` + + `| | |\n|---|---|\n` + + `| **Preview** | ${previewUrl} |\n` + + `| **Deployment** | ${env.DEPLOYMENT_URL} |\n` + + `| **Commit** | \`${env.HEAD_SHA.slice(0, 7)}\` |\n` + + `| **Triggered by** | @${context.actor} |\n` + + `| **Updated** | ${ts} |\n` + ); diff --git a/.github/zizmor.yml b/.github/zizmor.yml new file mode 100644 index 000000000..74f870a67 --- /dev/null +++ b/.github/zizmor.yml @@ -0,0 +1,10 @@ +rules: + dangerous-triggers: + ignore: + # Both preview workflows use pull_request_target so secrets are available + # for fork PRs. docs-preview.yml gates PR-code execution behind an + # admin/maintainer permission check and isolates the build (which runs + # PR Python via mkdocstrings) from Cloudflare secrets via an artifact + # handoff. docs-preview-cleanup.yml never checks out PR code at all. + - docs-preview.yml + - docs-preview-cleanup.yml From 24b3a5df27b70bfd3df2a3e2c94bfdd2684a6445 Mon Sep 17 00:00:00 2001 From: Den Delimarsky Date: Tue, 30 Jun 2026 15:16:03 +0000 Subject: [PATCH 2/3] Address review feedback on docs-preview workflows - Disable the uv Actions cache in the build job: pull_request_target runs share the base-branch cache scope, so a cache populated while untrusted PR code ran could poison later trusted workflows. Mirrors the posture in publish-pypi.yml. - Fix concurrency: workflow-level concurrency is evaluated before job if-conditions, so any PR comment was cancelling in-flight previews. Only runs that actually produce a preview now share a group; unrelated comment runs fall through to a unique run_id group. - Replace .github/zizmor.yml with inline ignore comments anchored to the pull_request_target lines (matching the existing pattern in claude.yml). - Raise the cleanup pagination cap to 200 pages. :house: Remote-Dev: homespace --- .github/workflows/docs-preview-cleanup.yml | 4 ++-- .github/workflows/docs-preview.yml | 18 +++++++++++++++--- .github/zizmor.yml | 10 ---------- 3 files changed, 17 insertions(+), 15 deletions(-) delete mode 100644 .github/zizmor.yml diff --git a/.github/workflows/docs-preview-cleanup.yml b/.github/workflows/docs-preview-cleanup.yml index 3e1cd70f1..136a50eff 100644 --- a/.github/workflows/docs-preview-cleanup.yml +++ b/.github/workflows/docs-preview-cleanup.yml @@ -5,7 +5,7 @@ name: Docs Preview Cleanup # checks out PR code, so there is no untrusted-code execution risk. on: - pull_request_target: + pull_request_target: # zizmor: ignore[dangerous-triggers] never checks out PR code types: [closed] permissions: {} @@ -30,7 +30,7 @@ jobs: # Collect matching ids across all pages first, then delete — deleting # mid-pagination would shift later pages and skip entries. ids="" - for page in $(seq 1 50); do + for page in $(seq 1 200); do resp=$(curl -fsS -H "Authorization: Bearer $CF_API_TOKEN" "$base?env=preview&per_page=25&page=$page") ids="$ids $(jq -r --arg b "$BRANCH" '.result[]? | select(.deployment_trigger.metadata.branch == $b) | .id' <<<"$resp")" [ "$(jq '.result | length' <<<"$resp")" -lt 25 ] && break diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml index 8b78585f2..ebc5e95a3 100644 --- a/.github/workflows/docs-preview.yml +++ b/.github/workflows/docs-preview.yml @@ -15,7 +15,7 @@ name: Docs Preview # - vars.CLOUDFLARE_PAGES_PROJECT (existing Pages project, e.g. mcp-python-sdk-docs) on: - pull_request_target: + pull_request_target: # zizmor: ignore[dangerous-triggers] build is permission-gated and secret-isolated; see header comment types: [opened, reopened, synchronize] paths: - docs/** @@ -28,7 +28,16 @@ on: permissions: {} concurrency: - group: docs-preview-pr-${{ github.event.pull_request.number || github.event.issue.number }} + # Workflow-level concurrency is evaluated when the run is queued — before any + # job-level `if:` — so an unrelated PR comment would otherwise cancel an + # in-flight build. Only runs that actually produce a preview share a group; + # everything else falls through to a unique run_id group. + group: >- + docs-preview-pr-${{ + github.event_name == 'pull_request_target' && github.event.pull_request.number + || (github.event.issue.pull_request && startsWith(github.event.comment.body, '/preview-docs') && github.event.issue.number) + || github.run_id + }} cancel-in-progress: true jobs: @@ -113,7 +122,10 @@ jobs: - name: Install uv uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0 with: - enable-cache: true + # pull_request_target runs share the base-branch Actions cache; saving + # a cache populated while untrusted PR code ran would let it poison + # later trusted workflows. Mirrors publish-pypi.yml. + enable-cache: false version: 0.9.5 - run: uv sync --frozen --group docs diff --git a/.github/zizmor.yml b/.github/zizmor.yml deleted file mode 100644 index 74f870a67..000000000 --- a/.github/zizmor.yml +++ /dev/null @@ -1,10 +0,0 @@ -rules: - dangerous-triggers: - ignore: - # Both preview workflows use pull_request_target so secrets are available - # for fork PRs. docs-preview.yml gates PR-code execution behind an - # admin/maintainer permission check and isolates the build (which runs - # PR Python via mkdocstrings) from Cloudflare secrets via an artifact - # handoff. docs-preview-cleanup.yml never checks out PR code at all. - - docs-preview.yml - - docs-preview-cleanup.yml From ea97b8374355a8be313fffd08c3adae9020f5d93 Mon Sep 17 00:00:00 2001 From: Den Delimarsky Date: Tue, 30 Jun 2026 15:36:31 +0000 Subject: [PATCH 3/3] Scope sticky-comment lookup to github-actions[bot] The upsert predicate matched any bot, so a comment from a different bot that quoted the marker string would have been overwritten with the preview table instead of the workflow's own comment. :house: Remote-Dev: homespace --- .github/workflows/docs-preview.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml index ebc5e95a3..05e8a877f 100644 --- a/.github/workflows/docs-preview.yml +++ b/.github/workflows/docs-preview.yml @@ -194,7 +194,7 @@ jobs: async function upsert(body) { const comments = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number, per_page: 100 }); - const existing = comments.find(c => c.user?.type === 'Bot' && c.body?.includes(marker)); + const existing = comments.find(c => c.user?.login === 'github-actions[bot]' && c.body?.includes(marker)); if (existing) { await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body }); } else {