Skip to content

HTML Recovery Tool: Restore lecture sites from GitHub Release assets #27

Closed

Description

@mmcky

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/cli later, if wanted. Listing recovery points across repos (gh release list) and triggering restores in several repos (gh workflow run restore.yml) are operator conveniences a qe command 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-pages composite action: download a release's archive and checksum (gh release download), verify the SHA256 before anything is deployed, extract, and deploy through the same configure-pages → upload-pages-artifact → deploy-pages path as publish-gh-pages. Inputs: tag (default: the latest release), asset-name (same default as publish-gh-pages, <repo>-html), github-token.
  • templates/restore.yml: workflow_dispatch with a tag input; contents: read, pages: write, id-token: write; shares publish.yml's pages concurrency 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 runs publish-gh-pages@v0 without release assets today): enable create-release-assets, publish, then restore an earlier tag.
  • Contract note in the user manual's publish-gh-pages chapter: 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 via softprops/action-gh-release SHA-pinned to v3.0.3 at :150
  • publish-gh-pages/README.md:77-93 describes the triple
  • workflow-backups PLAN.md ("Two Pillars") names this issue as the HTML-recovery pillar

Activity

  1. added a commit that references this issue on Mar 12, 2026
  2. added
    enhancementImprovement to existing content or functionality
    low-priorityNice to have, no time pressure
    on Aug 11, 2026
  3. quantecon-services commented on Sep 24, 2026

    @quantecon-services
    Collaborator

    Triage note, 2026-09-24:


    Generated by Claude Code

  4. mmcky commented on Sep 25, 2026

    @mmcky
    ContributorAuthor

    Home decided (2026-09-25): this repo, as a restore-gh-pages action plus a templates/restore.yml that lecture repos run by workflow_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-pages needs that workflow's pages: write and id-token: write), so neither workflow-backups nor a local CLI can perform the restore. workflow-backups gets nothing here, since the sources are the backup; a qe wrapper 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)

  5. added 2 commits that reference this issue on Sep 25, 2026
  6. mmcky commented on Nov 10, 2026

    @mmcky
    ContributorAuthor

    Checked against main at f627321. 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' mode input (#257) makes the deploy reusable. So restore-gh-pages downloads a release's archive and checksum, verifies the SHA-256 and extracts the site. templates/restore.yml then hands the site to publish-gh-pages, which deploys it as it deploys a build. The new action needs only contents: 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 an asset-name other than <repository>-html. So an empty asset-name finds the release's one *-<tag>.tar.gz rather 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-pages chapter 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-cn and lecture-python-programming.fa all deploy from a gh-pages branch. An Actions deploy doesn't serve those sites, and their branch history already holds every past site. Once one moves to publish-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.

    tag is 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 on main, shares publish.yml's pages concurrency 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-in gh, and checks the round trip, the hand-off to publish-gh-pages, and each refusal. In the canary, the release publish-staged-v0180, which publish-gh-pages made during v0.18.0's staging, is restored to the canary's Pages site from its main at 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-pages deploys; tag is required; an empty asset-name finds the release's one archive; no token input, with build-dir and commit as outputs; the checksum and manifest keep their names; only this repository's releases in the standard triple; and the canary test restores publish-staged-v0180.

    Claude Code (on behalf of mmcky)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementImprovement to existing content or functionalitylow-priorityNice to have, no time pressure

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions