Add Cloudflare Pages docs preview with /preview-docs slash command (#3028)
This commit is contained in:
Den Delimarsky
GitHub
parent
0b200ef03b
commit
985652491a
2 changed files with 275 additions and 0 deletions
44
.github/workflows/docs-preview-cleanup.yml
vendored
Normal file
44
.github/workflows/docs-preview-cleanup.yml
vendored
Normal file
|
|
@ -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: # zizmor: ignore[dangerous-triggers] never checks out PR code
|
||||||
|
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 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
|
||||||
|
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."
|
||||||
231
.github/workflows/docs-preview.yml
vendored
Normal file
231
.github/workflows/docs-preview.yml
vendored
Normal file
|
|
@ -0,0 +1,231 @@
|
||||||
|
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: # zizmor: ignore[dangerous-triggers] build is permission-gated and secret-isolated; see header comment
|
||||||
|
types: [opened, reopened, synchronize]
|
||||||
|
paths:
|
||||||
|
- docs/**
|
||||||
|
- docs_src/**
|
||||||
|
- mkdocs.yml
|
||||||
|
- pyproject.toml
|
||||||
|
issue_comment:
|
||||||
|
types: [created]
|
||||||
|
|
||||||
|
permissions: {}
|
||||||
|
|
||||||
|
concurrency:
|
||||||
|
# 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:
|
||||||
|
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:
|
||||||
|
# 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
|
||||||
|
- 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 = '<!-- docs-preview -->';
|
||||||
|
|
||||||
|
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?.login === 'github-actions[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`
|
||||||
|
);
|
||||||
Loading…
Reference in a new issue