Skip to content

ci: deploy docs via GitHub Actions to py.sdk.modelcontextprotocol.io #2632

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
maxisbey wants to merge 1 commit into from
+61 −36
Closed

ci: deploy docs via GitHub Actions to py.sdk.modelcontextprotocol.io #2632

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 60 additions & 0 deletions .github/workflows/deploy-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
name: Deploy Docs

on:
push:
branches:
- main
workflow_dispatch:

concurrency:
group: deploy-docs
cancel-in-progress: true

Check warning on line 11 in .github/workflows/deploy-docs.yml

View check run for this annotation

Claude / Claude Code Review

cancel-in-progress: true contradicts GitHub Pages deployment guidance 

GitHub's official Pages starter workflows set `cancel-in-progress: false` for the deploy concurrency group, with the rationale that production Pages deployments should be allowed to complete rather than be cancelled mid-flight — and the TypeScript SDK workflow this PR cites as prior art does the same. Consider flipping this to `false` so a second push to `main` queues behind an in-progress deploy instead of cancelling it.
Comment on lines +9 to +11
Copy link
Copy Markdown
Contributor

@claude claude Bot May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 GitHub's official Pages starter workflows set cancel-in-progress: false for the deploy concurrency group, with the rationale that production Pages deployments should be allowed to complete rather than be cancelled mid-flight — and the TypeScript SDK workflow this PR cites as prior art does the same. Consider flipping this to false so a second push to main queues behind an in-progress deploy instead of cancelling it.

Extended reasoning...

What it is. The new deploy-docs.yml declares a concurrency group with cancel-in-progress: true. GitHub's own Pages starter workflows (e.g. actions/starter-workflows/pages/mkdocs.yml, static.yml, jekyll.yml) all set this to false, with an explicit inline comment: "Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. However, do NOT cancel in-progress runs as we want to allow these production deployments to complete." The TypeScript SDK workflow that this PR's description cites as prior art (modelcontextprotocol/typescript-sdk#1584) also follows the false pattern.

The code path. With cancel-in-progress: true, two pushes to main in quick succession will cause the second run to cancel the first. If the first run is already inside the actions/deploy-pages step — after the artifact has been registered with the Pages API but before the deployment has been promoted — the cancellation aborts a production deployment mid-flight.

Why nothing else prevents it. The concurrency group correctly serialises runs (only one at a time), but cancel-in-progress: true overrides the default queueing behaviour. There's no other guard in the workflow that distinguishes "safe to cancel" (still building the site) from "don't cancel" (already calling the Pages deploy API).

Impact. In practice the blast radius is small: GitHub Pages deployments are largely atomic on the server side, so the most likely outcome of a cancelled deploy is that the previous version keeps serving, not a half-applied site. The newer push will deploy strictly newer content anyway. The realistic bad case is narrow — deploy A is cancelled, then deploy B fails for an unrelated reason, leaving you with no successful deploy when A would have landed. Still, it deviates from both GitHub's documented guidance and the prior art the PR explicitly follows.

Step-by-step example.

  1. Commit X is pushed to main → run A starts, builds the site, reaches actions/deploy-pages.
  2. Commit Y is pushed to main 30 seconds later → run B starts in the deploy-docs concurrency group.
  3. Because cancel-in-progress: true, GitHub cancels run A mid-way through the deploy-pages step.
  4. Run B builds and deploys commit Y. If B succeeds, all is well. If B fails (transient runner issue, broken build, etc.), the docs are now stale and there is no record of A having succeeded — even though A had already finished building and was deploying.

Fix. One-line change:

concurrency:
  group: deploy-docs
  cancel-in-progress: false

This matches GitHub's starter templates and the TS SDK workflow: the in-flight deploy is allowed to finish, intermediate queued runs are skipped, and only the latest queued run is kept.


jobs:
deploy-docs:
runs-on: ubuntu-latest

permissions:
contents: read
pages: write
id-token: write

environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}

steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

- name: Install uv
uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
with:
enable-cache: true
version: 0.9.5

- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
- uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
with:
key: mkdocs-material-${{ env.cache_id }}
path: .cache
restore-keys: |
mkdocs-material-

- run: uv sync --frozen --group docs

- name: Build docs
run: uv run --frozen --no-sync mkdocs build
env:
ENABLE_SOCIAL_CARDS: "true"

- name: Configure Pages
uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0

- name: Upload Pages artifact
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: site

- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
35 changes: 0 additions & 35 deletions .github/workflows/publish-docs-manually.yml
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ strict: true
repo_name: modelcontextprotocol/python-sdk
repo_url: https://github.com/modelcontextprotocol/python-sdk
edit_uri: edit/main/docs/
site_url: https://modelcontextprotocol.github.io/python-sdk
site_url: https://py.sdk.modelcontextprotocol.io/

# TODO(Marcelo): Add Anthropic copyright?
# copyright: © Model Context Protocol 2025 to present
Expand Down
Loading