Repository navigation
migrate: open github-pages env policy + fix migration ordering docs - #12
Merged
Merged
Conversation
scripts/migrate.sh: after flipping the Pages source, set the github-pages
environment's deployment_branch_policy to null ("no restriction") so deploys
from PR/tag refs — which run under the nested-publish model — aren't rejected
by the environment. Previously a manual step.
docs/how-to/migrate-from-gh-pages.md: correct the migration ordering.
- Flipping the Pages source to GitHub Actions is non-destructive: the last
gh-pages deployment keeps serving until the first Actions deploy supersedes
it (no downtime). Drop the earlier "blank site" / "PR-first, red publish
window" framing.
- The clean universal order is seed-first: seed the default branch before any
publish runs (a publish replaces the whole site), run the cutover before
merging the pipeline PR, and let that PR's CI be the first deploy. This makes
every publish safe — including on repos already serving Pages from Actions,
which is no longer a special case.
- Document the new env-policy step and the legacy-switcher gh-pages-deletion
caveat; correct the --delete-gh-pages guard wording (_sources/<default>.zip
is 200).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RBtsHDzshkwFgTJtrDVveU
Restructure the migration into two script runs with the pipeline PR's own publish doing the deploy in between, instead of the prepare run triggering and verifying a deploy itself: - prepare (default run): backfill + seed + flip Pages source + open the env policy, then STOP. Uploads and flips only — no deploy, no verify. (Flipping is non-destructive: the last gh-pages deployment keeps serving until the first Actions deploy.) Removes the interactive "trigger a deploy / press Enter / verify" steps and the --deploy-workflow flag. - the pipeline PR's CI runs the first publish (reads the seed, persists _sources/<default>.zip). - finalize (--delete-gh-pages): guard _sources is live, verify the live site, delete gh-pages + the seed. Rewrite the how-to around the three steps (prepare run → PR publishes → finalize run) and the "why this order" (non-destructive flip; seed before any publish). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RBtsHDzshkwFgTJtrDVveU
The docs set no favicon, so `myst build` fetched MyST's default favicon from
mystmd.org on every build; when that remote fetch flakes ("Premature close")
the build fails. Pin the favicon to the bundled dls-logo.svg so the build is
self-contained, and set logo_text to the repo name. (Same fix applied to the
PandABlocks consumers.)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RBtsHDzshkwFgTJtrDVveU
…tecture) - migrate-from-gh-pages: drop the "Why this order" explanation section (a how-to shouldn't carry it) and link to the architecture explanation instead. Move the "prepare the pipeline PR" prerequisite out of "Before you start" into Step 3, where it's actually used. - architecture: add a "Migrating from gh-pages" subsection holding the moved rationale (non-destructive source flip; whole-site-replace ⇒ seed before any publish), the anchor the how-to now links to. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RBtsHDzshkwFgTJtrDVveU
….yml The release job is required, not optional: assemble reconstructs each released version from a docs.zip asset on its GitHub Release, and tags get no _sources/ copy — so without it a tag's docs drop on the next deploy. The tutorial said "optional" and pointed at a non-existent "step 7". - Tutorial: new Step 6 "Add the release job (required)" that literalinclude's the generic steps (download docs.zip + attach to the Release) straight from this repo's _release.yml, so it can't drift; Step 7 is now "Cut your first release". - _release.yml: bracket those two steps with docs-literalinclude markers and a note to keep them; the version-switcher.mjs checkout+cp stays outside the markers (plugin-specific). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RBtsHDzshkwFgTJtrDVveU
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RBtsHDzshkwFgTJtrDVveU
… around a PR - Merge the old "add the release job" step into Step 3, so the reader writes ci.yml once (docs + release + publish), with the release steps still literalinclude'd from _release.yml. - Reframe the deploy steps around the normal PR flow: Step 5 "push your branch and open a PR" explains what the docs/publish checks do and the /pr-<n>/ preview (plus the one-time fresh-repo bootstrap where publish is red until main exists); Step 6 "merge to main — your first deploy"; Step 7 "cut your first release". Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RBtsHDzshkwFgTJtrDVveU
Log etag/last-modified/age/x-served-by/x-cache each poll and stretch the window 60s→180s so a wedged Pages origin (etag pinned while age climbs) is unmistakable vs slow CDN propagation. Temporary, to diagnose the tag-after-main publish wedge; revert once we have the data. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This branch was previously deployed
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two related migration improvements, prompted by executing the PandABlocks-server cutover.
scripts/migrate.sh— open thegithub-pagesenv policy (was a manual step)After flipping the Pages source, set the
github-pagesenvironment'sdeployment_branch_policytonull("no restriction"), so deploys from PR/tag refs —which run under the nested-publish model — aren't rejected by the environment. Added as
cutover step 2b; idempotent (
PUT …/environments/github-pages).docs/how-to/migrate-from-gh-pages.md— correct the orderinggh-pagesdeployment keeps serving until the first Actions deploy supersedes it (community
discussion #158055) — no
downtime. Removes the earlier incorrect "blank site" / "PR-first with a red publish
window" framing.
publishruns (a publish replaces the whole site), run the cutover before mergingthe pipeline PR, and let that PR's CI be the first deploy. Repos already serving Pages
from Actions are no longer a special case — seeding first makes every publish safe.
and corrects the
--delete-gh-pagesguard wording (_sources/<default>.zipis200).🤖 Generated with Claude Code