Field alias is published in the tool schema but forwarded as an invalid Python keyword #238
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: Docs Preview | |
| # Builds the docs site for a PR and deploys it to Cloudflare Pages. | |
| # | |
| # Security: the build executes Python from the PR (mkdocstrings imports | |
| # src/mcp, `!!python/name:` config directives run, and heads may ship their | |
| # own build scripts). 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 | |
| - scripts/docs/** | |
| - 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 | |
| # pull_request_target runs this workflow file from the base branch, so | |
| # the whole recipe — dependency sync included — must come from the | |
| # checkout itself: heads that ship scripts/docs/build.sh (the Zensical | |
| # toolchain) build with it; older heads, and v1.x heads previewed via | |
| # /preview-docs, still build with MkDocs. Both arms must write the site | |
| # to site/. Keep the detection in sync with build_site() in | |
| # scripts/build-docs.sh. | |
| - run: | | |
| if [ -f scripts/docs/build.sh ]; then | |
| bash scripts/docs/build.sh | |
| else | |
| uv sync --frozen --group docs | |
| # The env var silences mkdocs-material's MkDocs 2.0 warning banner. | |
| NO_MKDOCS_2_WARNING=1 uv run --frozen --no-sync mkdocs build | |
| fi | |
| - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 | |
| with: | |
| name: site | |
| path: site/ | |
| retention-days: 1 | |
| # An empty site/ means the build arm broke its output contract; fail | |
| # here instead of surfacing as a confusing download error in deploy. | |
| if-no-files-found: error | |
| 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` | |
| ); |