Skip to content

Commit 3d2fa5f

Browse files
fix(pages): bypass CDN cache in content comparison via GitHub API (#348)
GitHub Pages' Fastly CDN caches responses with max-age=600 and ignores all client cache-bypass headers (Cache-Control: no-cache, Pragma: no-cache, ?t= query-string variations). Three consecutive master CI runs failed at the "Verify live site serves the newest post" step because content_matches() was polling the live CDN URL and consistently saw stale content for the full 15-minute timeout window. Switch content_matches() to fetch from the gh-pages branch via the GitHub Contents API, which bypasses the CDN entirely. The feed-URL check in get_live_links() still uses the live CDN URL so Pages build failures (original 2026-11-07 incident) are still detected: if Pages fails to publish, the feed URL stays absent from the live feed. 20/20 tests pass. Git-Session-Id: 209e30bc-894b-41c8-a569-ec375cabdd6e
1 parent 7d76081 commit 3d2fa5f

2 files changed

Lines changed: 29 additions & 8 deletions

File tree

‎scripts/check_live_deploy.py‎

Lines changed: 27 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,17 @@
66
(2026-11-07: the 03:06Z and 18:04Z builds errored while the workflow was green,
77
so the site served stale content for ~15 hours). This check takes the first
88
``<item><link>`` of the local ``_site/feed.xml`` and requires it to appear in the
9-
live feed with its rendered page matching the local build. A permalink alone
10-
cannot detect stale content after an edit. Poll while Pages catches up, and
11-
ask Pages to rebuild once if it does not.
9+
live feed, and verifies the rendered post content against the ``gh-pages``
10+
branch via the GitHub API. A permalink alone cannot detect stale content after
11+
an edit. Poll while Pages catches up, and ask Pages to rebuild once if it does
12+
not.
13+
14+
The CDN (Fastly, max-age=600) ignores client cache-bypass headers such as
15+
``Cache-Control: no-cache`` and ``?t=`` query-string variations — it caches
16+
responses regardless. Live-URL content polling is therefore unreliable right
17+
after a deploy. The feed check still uses the live URL (to detect Pages
18+
build failures), while the content comparison bypasses the CDN via the
19+
GitHub API.
1220
"""
1321

1422
from __future__ import annotations
@@ -133,16 +141,28 @@ def main() -> int:
133141
if local_post.is_dir():
134142
local_post = local_post / "index.html"
135143
expected_content = comparable_html(local_post.read_bytes().decode("utf-8"))
136-
post_url = f"{args.live_url.rstrip('/')}{post_path}"
137144
feed_url = f"{args.live_url.rstrip('/')}/feed.xml"
138145

146+
# Relative path of the post inside the deployed site root (== gh-pages root).
147+
gh_post_path = str(local_post.relative_to(site_dir))
148+
139149
def content_matches() -> bool:
140-
return (
141-
comparable_html(fetch(f"{post_url}?t={time.time_ns()}")) == expected_content
150+
# Bypass the CDN: compare against gh-pages via GitHub API.
151+
raw = fetch(
152+
f"https://api.github.com/repos/{args.repository}/contents/{gh_post_path}?ref=gh-pages",
153+
headers={
154+
"Accept": "application/vnd.github.v3.raw",
155+
"Authorization": f"Bearer {args.token}",
156+
"X-GitHub-Api-Version": "2022-11-28",
157+
},
142158
)
159+
return comparable_html(raw) == expected_content
143160

144161
def get_live_links() -> list[str]:
145-
# Query string defeats intermediate caches; Pages ignores it.
162+
# Use the live CDN feed to detect Pages build failures: if Pages does
163+
# not publish the new content, this URL stays absent from the live feed.
164+
# The CDN ignores ?t= cache-busters, but the feed URL itself is
165+
# sufficient to detect whether Pages rebuilt successfully.
146166
return item_links(fetch(f"{feed_url}?t={int(time.time())}"))
147167

148168
def rebuild() -> None:

‎tests/test_check_live_deploy.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -203,4 +203,5 @@ def fetch(url, headers=None, method="GET"):
203203
],
204204
)
205205
assert live.main() == (0 if current else 1)
206-
assert any("/blog/b/?t=" in url for url, _ in requests)
206+
# content_matches() fetches via GitHub API (bypasses CDN), not the live CDN URL
207+
assert any("contents/blog/b/index.html" in url for url, _ in requests)

0 commit comments

Comments
 (0)