Skip to content

Commit 9856524

Browse files
localdenlocalden
authored
Add Cloudflare Pages docs preview with /preview-docs slash command (#3028)
1 parent 0b200ef commit 9856524

2 files changed

Lines changed: 275 additions & 0 deletions

File tree

‎.github/workflows/docs-preview-cleanup.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Docs Preview Cleanup
2+
3+
# Deletes Cloudflare Pages preview deployments for a PR when it closes.
4+
# Runs as pull_request_target so secrets are available for fork PRs; it never
5+
# checks out PR code, so there is no untrusted-code execution risk.
6+
7+
on:
8+
pull_request_target: # zizmor: ignore[dangerous-triggers] never checks out PR code
9+
types: [closed]
10+
11+
permissions: {}
12+
13+
jobs:
14+
cleanup:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Delete preview deployments for this PR
18+
env:
19+
CF_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
20+
CF_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
21+
CF_PROJECT: ${{ vars.CLOUDFLARE_PAGES_PROJECT }}
22+
BRANCH: pr-${{ github.event.pull_request.number }}
23+
run: |
24+
set -euo pipefail
25+
if [ -z "$CF_API_TOKEN" ] || [ -z "$CF_ACCOUNT_ID" ] || [ -z "$CF_PROJECT" ]; then
26+
echo "Cloudflare credentials/project not configured; skipping cleanup."
27+
exit 0
28+
fi
29+
base="https://api.cloudflare.com/client/v4/accounts/$CF_ACCOUNT_ID/pages/projects/$CF_PROJECT/deployments"
30+
# Collect matching ids across all pages first, then delete — deleting
31+
# mid-pagination would shift later pages and skip entries.
32+
ids=""
33+
for page in $(seq 1 200); do
34+
resp=$(curl -fsS -H "Authorization: Bearer $CF_API_TOKEN" "$base?env=preview&per_page=25&page=$page")
35+
ids="$ids $(jq -r --arg b "$BRANCH" '.result[]? | select(.deployment_trigger.metadata.branch == $b) | .id' <<<"$resp")"
36+
[ "$(jq '.result | length' <<<"$resp")" -lt 25 ] && break
37+
done
38+
deleted=0
39+
for id in $ids; do
40+
echo "Deleting deployment $id"
41+
curl -fsS -X DELETE -H "Authorization: Bearer $CF_API_TOKEN" "$base/$id?force=true" > /dev/null
42+
deleted=$((deleted + 1))
43+
done
44+
echo "Deleted $deleted deployment(s) for $BRANCH."

‎.github/workflows/docs-preview.yml‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
name: Docs Preview
2+
3+
# Builds the mkdocs site for a PR and deploys it to Cloudflare Pages.
4+
#
5+
# Security: mkdocs executes Python from the PR (mkdocstrings imports src/mcp,
6+
# `!!python/name:` directives). The build is gated by `authorize` (admin sender
7+
# for auto-preview, admin/maintainer commenter for /preview-docs) and isolated
8+
# from Cloudflare secrets — `build` runs PR code with no secrets and hands the
9+
# static site to `deploy` via an artifact, so PR code never shares a runner
10+
# with the Cloudflare token.
11+
#
12+
# Required configuration:
13+
# - secrets.CLOUDFLARE_API_TOKEN (scope: Account → Cloudflare Pages → Edit)
14+
# - secrets.CLOUDFLARE_ACCOUNT_ID
15+
# - vars.CLOUDFLARE_PAGES_PROJECT (existing Pages project, e.g. mcp-python-sdk-docs)
16+
17+
on:
18+
pull_request_target: # zizmor: ignore[dangerous-triggers] build is permission-gated and secret-isolated; see header comment
19+
types: [opened, reopened, synchronize]
20+
paths:
21+
- docs/**
22+
- docs_src/**
23+
- mkdocs.yml
24+
- pyproject.toml
25+
issue_comment:
26+
types: [created]
27+
28+
permissions: {}
29+
30+
concurrency:
31+
# Workflow-level concurrency is evaluated when the run is queued — before any
32+
# job-level `if:` — so an unrelated PR comment would otherwise cancel an
33+
# in-flight build. Only runs that actually produce a preview share a group;
34+
# everything else falls through to a unique run_id group.
35+
group: >-
36+
docs-preview-pr-${{
37+
github.event_name == 'pull_request_target' && github.event.pull_request.number
38+
|| (github.event.issue.pull_request && startsWith(github.event.comment.body, '/preview-docs') && github.event.issue.number)
39+
|| github.run_id
40+
}}
41+
cancel-in-progress: true
42+
43+
jobs:
44+
authorize:
45+
if: >-
46+
github.event_name == 'pull_request_target' ||
47+
(github.event.issue.pull_request && startsWith(github.event.comment.body, '/preview-docs'))
48+
runs-on: ubuntu-latest
49+
permissions:
50+
contents: read
51+
pull-requests: read
52+
outputs:
53+
authorized: ${{ steps.check.outputs.authorized }}
54+
pr_number: ${{ steps.check.outputs.pr_number }}
55+
head_sha: ${{ steps.check.outputs.head_sha }}
56+
slash_attempt: ${{ steps.check.outputs.slash_attempt }}
57+
steps:
58+
- name: Determine authorization
59+
id: check
60+
uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
61+
with:
62+
script: |
63+
const { owner, repo } = context.repo;
64+
65+
async function permissionFor(username) {
66+
const { data } = await github.rest.repos.getCollaboratorPermissionLevel({ owner, repo, username });
67+
return { level: data.permission, role: data.role_name };
68+
}
69+
70+
let authorized = false;
71+
let prNumber = '';
72+
let headSha = '';
73+
let slashAttempt = false;
74+
75+
if (context.eventName === 'pull_request_target') {
76+
// Gate on the *sender* (whoever caused this run — on synchronize that
77+
// is the pusher), not the PR author, so a non-admin pushing to an
78+
// admin-opened branch does not get an automatic build.
79+
const actor = context.payload.sender.login;
80+
prNumber = String(context.payload.pull_request.number);
81+
headSha = context.payload.pull_request.head.sha;
82+
const perm = await permissionFor(actor);
83+
authorized = perm.level === 'admin';
84+
core.info(`pull_request_target by ${actor} (level=${perm.level}, role=${perm.role}) → authorized=${authorized}`);
85+
} else {
86+
// issue_comment: the job-level `if:` already guarantees this is a PR
87+
// comment starting with /preview-docs.
88+
slashAttempt = true;
89+
const actor = context.payload.comment.user.login;
90+
prNumber = String(context.payload.issue.number);
91+
const perm = await permissionFor(actor);
92+
authorized = perm.level === 'admin' || perm.role === 'maintain';
93+
if (authorized) {
94+
const { data: pr } = await github.rest.pulls.get({ owner, repo, pull_number: Number(prNumber) });
95+
if (pr.state !== 'open') {
96+
authorized = false;
97+
core.info(`PR #${prNumber} is ${pr.state}; refusing to preview.`);
98+
} else {
99+
headSha = pr.head.sha;
100+
}
101+
}
102+
core.info(`/preview-docs by ${actor} (level=${perm.level}, role=${perm.role}) → authorized=${authorized}`);
103+
}
104+
105+
core.setOutput('authorized', String(authorized));
106+
core.setOutput('pr_number', prNumber);
107+
core.setOutput('head_sha', headSha);
108+
core.setOutput('slash_attempt', String(slashAttempt));
109+
110+
build:
111+
needs: authorize
112+
if: needs.authorize.outputs.authorized == 'true'
113+
runs-on: ubuntu-latest
114+
permissions:
115+
contents: read
116+
steps:
117+
- uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
118+
with:
119+
ref: ${{ needs.authorize.outputs.head_sha }}
120+
persist-credentials: false
121+
122+
- name: Install uv
123+
uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
124+
with:
125+
# pull_request_target runs share the base-branch Actions cache; saving
126+
# a cache populated while untrusted PR code ran would let it poison
127+
# later trusted workflows. Mirrors publish-pypi.yml.
128+
enable-cache: false
129+
version: 0.9.5
130+
131+
- run: uv sync --frozen --group docs
132+
- run: uv run --frozen --no-sync mkdocs build
133+
134+
- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
135+
with:
136+
name: site
137+
path: site/
138+
retention-days: 1
139+
140+
deploy:
141+
needs: [authorize, build]
142+
if: needs.authorize.outputs.authorized == 'true'
143+
runs-on: ubuntu-latest
144+
permissions: {}
145+
outputs:
146+
deployment_url: ${{ steps.wrangler.outputs.deployment-url }}
147+
alias_url: ${{ steps.wrangler.outputs.pages-deployment-alias-url }}
148+
steps:
149+
- uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
150+
with:
151+
name: site
152+
path: site
153+
154+
- name: Deploy to Cloudflare Pages
155+
id: wrangler
156+
uses: cloudflare/wrangler-action@ebbaa1584979971c8614a24965b4405ff95890e0 # v4.0.0
157+
with:
158+
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
159+
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
160+
packageManager: npm
161+
command: >-
162+
pages deploy ./site
163+
--project-name=${{ vars.CLOUDFLARE_PAGES_PROJECT }}
164+
--branch=pr-${{ needs.authorize.outputs.pr_number }}
165+
--commit-hash=${{ needs.authorize.outputs.head_sha }}
166+
--commit-dirty=true
167+
168+
comment:
169+
needs: [authorize, build, deploy]
170+
if: >-
171+
always() &&
172+
needs.deploy.result != 'cancelled' &&
173+
(needs.authorize.outputs.authorized == 'true' || needs.authorize.outputs.slash_attempt == 'true')
174+
runs-on: ubuntu-latest
175+
permissions:
176+
pull-requests: write
177+
steps:
178+
- name: Post or update preview comment
179+
uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
180+
env:
181+
AUTHORIZED: ${{ needs.authorize.outputs.authorized }}
182+
PR_NUMBER: ${{ needs.authorize.outputs.pr_number }}
183+
HEAD_SHA: ${{ needs.authorize.outputs.head_sha }}
184+
DEPLOY_RESULT: ${{ needs.deploy.result }}
185+
DEPLOYMENT_URL: ${{ needs.deploy.outputs.deployment_url }}
186+
ALIAS_URL: ${{ needs.deploy.outputs.alias_url }}
187+
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
188+
with:
189+
script: |
190+
const { owner, repo } = context.repo;
191+
const env = process.env;
192+
const issue_number = Number(env.PR_NUMBER);
193+
const marker = '<!-- docs-preview -->';
194+
195+
async function upsert(body) {
196+
const comments = await github.paginate(github.rest.issues.listComments, { owner, repo, issue_number, per_page: 100 });
197+
const existing = comments.find(c => c.user?.login === 'github-actions[bot]' && c.body?.includes(marker));
198+
if (existing) {
199+
await github.rest.issues.updateComment({ owner, repo, comment_id: existing.id, body });
200+
} else {
201+
await github.rest.issues.createComment({ owner, repo, issue_number, body });
202+
}
203+
}
204+
205+
if (env.AUTHORIZED !== 'true') {
206+
await github.rest.issues.createComment({
207+
owner, repo, issue_number,
208+
body: `@${context.actor} — only repository admins or maintainers can run \`/preview-docs\` (and the PR must be open).`,
209+
});
210+
return;
211+
}
212+
213+
if (env.DEPLOY_RESULT !== 'success') {
214+
await upsert(
215+
`${marker}\n### 📚 Documentation preview\n\n` +
216+
`❌ Preview build **failed** for \`${env.HEAD_SHA.slice(0, 7)}\` — [workflow logs](${env.RUN_URL}).`
217+
);
218+
return;
219+
}
220+
221+
const previewUrl = env.ALIAS_URL || env.DEPLOYMENT_URL;
222+
const ts = new Date().toISOString().replace('T', ' ').replace(/\.\d+Z$/, ' UTC');
223+
await upsert(
224+
`${marker}\n### 📚 Documentation preview\n\n` +
225+
`| | |\n|---|---|\n` +
226+
`| **Preview** | ${previewUrl} |\n` +
227+
`| **Deployment** | ${env.DEPLOYMENT_URL} |\n` +
228+
`| **Commit** | \`${env.HEAD_SHA.slice(0, 7)}\` |\n` +
229+
`| **Triggered by** | @${context.actor} |\n` +
230+
`| **Updated** | ${ts} |\n`
231+
);

0 commit comments

Comments
 (0)