Repository navigation
Description
Producer live: lecture-python.myst, lecture-python-intro, lecture-python-advanced.myst, lecture-python-programming, lecture-python-programming.fr, lecture-jax, lecture-dp and continuous_time_mcs pass create-release-assets: 'true' to publish-gh-pages, and each release carries the triple — tarball, SHA256 checksum, JSON manifest (name, tag, commit, timestamp, size_mb, file_count, repository). The step that builds the triple is unchanged from v0.8.0 to main (only the upload action's pin has moved), so asset shape is identical across the pins those eight use (v0, v0.11.1). Missing is the consumer; built HTML is costly to reproduce, so a downed site recovers fastest from the archive.
Decision: home (2026-09-25)
Build it here, as the inverse of publish-gh-pages. A Pages site whose source is GitHub Actions can only be deployed from an Actions run in its own repository: deploy-pages needs that workflow's pages: write and id-token: write. So the restore has to be a workflow in each lecture repo, which makes it an action in this repo, next to the producer whose asset contract it reads. Fixes to that contract (see Gaps) and the consumer then land in the same PR, with no cross-repo version skew.
- Not
workflow-backups. That repo runs scheduled git-mirror backups to S3, and its own PLAN.md already assigns this tool to this issue. The release archives do not need an off-GitHub copy: the sources are the backup. QuantEcon/clilater, if wanted. Listing recovery points across repos (gh release list) and triggering restores in several repos (gh workflow run restore.yml) are operator conveniences aqecommand could wrap once the restore workflow exists. Not in this issue.
The custom domain needs nothing from the restore: with an Actions Pages source it lives in Settings → Pages, not in a CNAME file.
Scope
-
restore-gh-pagescomposite action: download a release's archive and checksum (gh release download), verify the SHA256 before anything is deployed, extract, and deploy through the sameconfigure-pages→upload-pages-artifact→deploy-pagespath aspublish-gh-pages. Inputs:tag(default: the latest release),asset-name(same default aspublish-gh-pages,<repo>-html),github-token. -
templates/restore.yml:workflow_dispatchwith ataginput;contents: read,pages: write,id-token: write; sharespublish.yml'spagesconcurrency group so a restore and a publish cannot race. Lecture repos add it before they need it. - Namespace the checksum and manifest names by tag (Gaps, third item), with the restore action still reading the current tag-less names on existing releases.
- Test end to end in the canary (
test-actions-lecture-intro, which runspublish-gh-pages@v0without release assets today): enablecreate-release-assets, publish, then restore an earlier tag. - Contract note in the user manual's
publish-gh-pageschapter: tracked in docs(manual): chapters for the remaining seven actions, and delete QUICK-REFERENCE.md #190.
Gaps
Two asset formats. lecture-julia.myst, lecture-python.zh-cn, lecture-intro.zh-cn, lecture-python-programming.fa hand-roll the triple in their own publish.yml (tar + sha256sum + heredoc manifest, uploaded via softprops/action-gh-release directly, @v2 in the first, @v3 in the rest): same <name>-html-<tag>.tar.gz, but checksum and manifest are the bare html-checksum.txt / html-manifest.json with no asset-name prefix, and the manifest omits name and repository. Handle both, or migrate those four onto publish-gh-pages first.
Tag-triggered publishes only. publish-gh-pages/action.yml:93-97 skips off-tag with a warning, and lecture-dp's publish.yml also accepts workflow_dispatch, so a manual publish there leaves no recovery point. Nine active repos attach nothing — lecture-datascience.myst, lecture-dle, lecture-dps, lecture-dynamics, lecture-eqm, lecture-stats, lecture-tools-techniques, lecture-python-programming.ml, lecture-python-programming.zh-cn deploy via peaceiris/actions-gh-pages or actions/deploy-pages with no archive step, outside recovery until they adopt create-release-assets.
Checksum/manifest names carry no tag. publish-gh-pages/action.yml:119-120 builds both from ASSET_NAME alone while the archive name at :111 includes the tag, so one repo's recovery points collide in a directory — namespace by repo and tag.
Related
- Producer
publish-gh-pages/action.yml:83-157(create-release-assets): guards:90-101, naming:103-111, checksum:126, manifest:129-138, upload viasoftprops/action-gh-releaseSHA-pinned to v3.0.3 at:150 publish-gh-pages/README.md:77-93describes the tripleworkflow-backupsPLAN.md ("Two Pillars") names this issue as the HTML-recovery pillar
Activity
Add improvement plan for backup strategy
quantecon-services commentedon Sep 24, 2026
Triage note, 2026-09-24:
publish-gh-pageschapter.workflow-backups". If that holds, transfer this issue to QuantEcon/workflow-backups. The tools used for this triage can't transfer issues, so this is left for a maintainer.Generated by Claude Code
mmcky commentedon Sep 25, 2026
Home decided (2026-09-25): this repo, as a
restore-gh-pagesaction plus atemplates/restore.ymlthat lecture repos run byworkflow_dispatch. The body is rescoped to match. The deciding constraint: a Pages site with a GitHub Actions source can only be deployed from an Actions run in its own repo (deploy-pagesneeds that workflow'spages: writeandid-token: write), so neitherworkflow-backupsnor a local CLI can perform the restore.workflow-backupsgets nothing here, since the sources are the backup; aqewrapper for listing and batch-triggering restores stays a possible later follow-up in QuantEcon/cli. The transfer suggested in the triage note above no longer applies.Assisted-by: Claude Code (Claude Opus 5.5)
docs(plan): record #27's home — a restore action in this repo (#200)
docs(manual): chapters for the other seven actions, and delete QUICK-…
mmcky commentedon Nov 10, 2026
Checked against
mainatf627321. The action and the template hold, and the home decided on 2026-09-25 stands. Five parts of the body change.The deploy:
publish-gh-pages'modeinput (#257) makes the deploy reusable. Sorestore-gh-pagesdownloads a release's archive and checksum, verifies the SHA-256 and extracts the site.templates/restore.ymlthen hands the site topublish-gh-pages, which deploys it as it deploys a build. The new action needs onlycontents: read, and the deploy is the one the release gate tests on every release.The asset name: four of the eight producers (
lecture-python.myst,lecture-python-advanced.myst,lecture-python-programming.fr,continuous_time_mcs) pass anasset-nameother than<repository>-html. So an emptyasset-namefinds the release's one*-<tag>.tar.gzrather than assume the default.The rename: the checksum and manifest keep their names. A restore downloads one release into a directory of its own, and the
publish-gh-pageschapter already says to keep each release's files apart. Renaming them would change a documented contract that eight repositories' releases already follow, for a collision only a many-release mirror would meet.The hand-rolled format:
lecture-julia.myst,lecture-python.zh-cn,lecture-intro.zh-cnandlecture-python-programming.faall deploy from agh-pagesbranch. An Actions deploy doesn't serve those sites, and their branch history already holds every past site. Once one moves topublish-gh-pages, its new releases have the standard names.The contract note: done in #190. The chapter's Release assets section documents the triple as a contract.
tagis required, since after a bad publish the latest release is the bad site. The restore reads only this repository's releases. The archive is verified before it is extracted, and an archive holding anything but files and directories is refused. The template dispatches onmain, sharespublish.yml'spagesconcurrency group, and runs in one job, since nothing in it runs repository code. The next publish replaces the restored site.Testing: the harness packs a site with
publish-gh-pages' own packing script, restores it through a stand-ingh, and checks the round trip, the hand-off topublish-gh-pages, and each refusal. In the canary, the releasepublish-staged-v0180, whichpublish-gh-pagesmade during v0.18.0's staging, is restored to the canary's Pages site from itsmainat release, after a gate run has replaced that site. The site must then serve the archive's files, compared by content.The maintainer's decisions, 2026-11-10: all seven recommendations accepted. The restore downloads, verifies and extracts, and
publish-gh-pagesdeploys;tagis required; an emptyasset-namefinds the release's one archive; no token input, withbuild-dirandcommitas outputs; the checksum and manifest keep their names; only this repository's releases in the standard triple; and the canary test restorespublish-staged-v0180.Claude Code (on behalf of mmcky)
feat(restore-gh-pages): restore a GitHub Pages site from a release (#27…
docs(plan): v0 is on v0.18.0; every publish-gh-pages consumer makes r…
ci(harness): restore-round-trip uploads no github-pages artifact (#27) (