Skip to content

fix(preview-*): surface deploy errors, pin the CLIs by lockfile, keep the Netlify token off argv (#105) - #174

Merged
mmcky merged 7 commits into
mainfrom
claude/105-preview-deploy
Sep 24, 2026
Merged

mmcky merged 7 commits into
mainfrom
claude/105-preview-deploy

Conversation

@quantecon-services

@quantecon-services quantecon-services commented Sep 23, 2026 •

Copy link
Copy Markdown
Collaborator

This is the code half of #105; the README pull_request_target warning shipped in #170. Both providers are verified with real deploys (see Real-deploy verification). The release carrying this is staged per decision 4 on #110.

Changes

Deploy errors now surface (preview-cloudflare, preview-netlify)

  • Cloudflare. DEPLOY_OUTPUT=$(wrangler … 2>&1) aborted under the composite shell's -eo pipefail with wrangler's stderr still in the variable, so a failed deploy logged nothing past "Deploying preview…". The capture is now:

    set +e
    "$WRANGLER" pages deploy … 2>&1 | tee "$LOG"
    EXIT=${PIPESTATUS[0]}
    set -e

    It runs inside a ::group::. On failure the step prints the output and emits ::error::wrangler pages deploy failed (exit N), then exits with wrangler's code. Note that fix(preview): surface deploy errors, pin CLIs, remove unsafe fork guidance #105's sketch (… | tee …; EXIT=${PIPESTATUS[0]} without set +e) would still abort before EXIT=; I verified that. The deployment-url extraction reads the log and is unchanged.

  • Netlify. Only stdout is teed to a file, because that is where --json writes. Merging stderr would corrupt the JSON on a successful deploy that prints npm or Node notices, and the now non-fatal parse would then fail a green deploy. The parse is python3 … < "$JSON" 2>/dev/null || true, so the "Raw output was:" guard is reachable for non-JSON, empty or URL-less output, followed by ::error:: and exit 1.

CLIs pinned by lockfile (decision 2 on #110)

  • preview-cloudflare/package.json + package-lock.json pin wrangler 4.136.3, the same version feat: deploy-cloudflare — publish private sites to a Worker behind Access, and prove they are gated (#163) #176 pins for deploy-cloudflare. preview-netlify/package.json + package-lock.json pin netlify-cli 27.8.1.
    • The locks are lockfileVersion 3, generated on linux-x64 with the containers' Node 24.21.0 / npm 11.19.0. Every entry resolves to registry.npmjs.org with an integrity hash.
    • The Linux optional packages are present: @cloudflare/workerd-linux-64 and @esbuild/linux-x64.
  • Install step. npm install -g <cli>@latest is replaced by npm ci into a fresh mktemp -d directory under RUNNER_TEMP, the same place deploy-cloudflare installs, copying the two files from $GITHUB_ACTION_PATH.
    • It does not install into the action directory, which in container jobs is the host-mounted _actions dir.
    • The runner clears RUNNER_TEMP between jobs, so nothing accumulates on a persistent runner.
    • Install scripts stay on, since workerd, esbuild and netlify-cli need them.
    • It verifies <cli> --version, emits ::error:: if npm ci or the binary fails, and outputs the absolute bin, which the deploy steps call.
    • For compatibility with the old global install, only the CLI's own executables are linked into a bin/ directory on GITHUB_PATH: wrangler/wrangler2/cf-wrangler and netlify/ntl. The dependency bins in node_modules/.bin (esbuild, tsc, semver, …) do not shadow the caller's tools.
  • Dependabot. A single npm entry in .github/dependabot.yml covers all three CLI directories: /deploy-cloudflare, which feat: deploy-cloudflare — publish private sites to a Worker behind Access, and prove they are gated (#163) #176 added, plus /preview-cloudflare and /preview-netlify. It keeps the npm and npm-major groups, so the wrangler pins move together, with one PR per update type.

Netlify inputs moved into env: (PLAN item 8)

  • No ${{ }} remains in the deploy run:.
  • The token and site now arrive as NETLIFY_AUTH_TOKEN and NETLIFY_SITE_ID, which netlify-cli 27.8.1 reads natively. I checked its source: getToken() falls back to the env token, and deploy --site defaults to env.NETLIFY_SITE_ID.
  • --auth and --site are therefore dropped. The token is no longer on argv or in the step script the runner writes to disk.
  • netlify deploy now passes --no-build, which is defined in netlify-cli 27.8.1's dist/commands/deploy/index.js:48. The site is prebuilt, so no configured build command runs in a process that inherits the token.

Harness. New preview-cli-install job. On setup-node@v7 with Node 24 it runs npm ci from each lockfile and requires <cli> --version to match package.json, so a Dependabot CLI bump is not merged with zero signal. It is gated and listed in harness-summary alongside #173's and #176's jobs; the lockfiles are added to the gate's must-run list.

Docs and changelog

  • Both READMEs' Requirements sections say the CLI is pinned in package.json, installed with npm ci (which needs registry.npmjs.org), and bumped by Dependabot. They no longer quote a version number, which would go stale on the first bump.
  • The Netlify README's stale "jq" requirement is corrected to python3, which the action has used since 0.5.1.
  • CHANGELOG entries are under Changed, Fixed, Security and Added.

Validation

Real-deploy verification

  • Cloudflare, locally, through the action's own deploy step (comment). This ran at 544b4b6 against a throwaway Direct Upload project qe-preview-canary.
    • Two deploys for PR 999 both returned deploy-url https://pr-999.qe-preview-canary.pages.dev, plus a different hash deployment-url each time.
    • The alias serves the newer build, and each hash URL its own build.
    • A bogus token gave wrangler's Authentication failed [code: 9106] inside the group, then ::error::, with no outputs.
  • Both providers from a same-repo canary PR (comment). This was ci: validate the QuantEcon/actions#174 preview actions (not for merging) test-actions-lecture-intro#65, running this branch's actions in the quantecon-build container (run 35950081155).
    • preview-cloudflare.
      • npm ci landed under /__w/_temp/preview-cloudflare.XXXXXX and reported wrangler 4.136.3.
      • The deploy uploaded 173 files, with wrangler's output inside the group.
      • It printed https://pr-65.qe-preview-canary.pages.dev and the pinned hash URL, and the PR comment carries both.
      • The alias serves the built site.
    • preview-netlify.
      • npm ci on the container's Node 24.21.0 reported netlify-cli 27.8.1.
      • The deploy ran with --no-build, with NETLIFY_AUTH_TOKEN and NETLIFY_SITE_ID arriving as masked env vars and nothing on argv.
      • --json parsed to https://pr-65--jade-tarsier-d98a19.netlify.app, and the PR comment posted.
    • Failure path, in CI. The first run went out with the token secret empty. wrangler's "In a non-interactive environment, it's necessary to set a CLOUDFLARE_API_TOKEN" appeared inside the group, then ::error::wrangler pages deploy failed (exit 1), and the job went visibly red. On main the same run ends silently after "Deploying preview".
    • Not re-run: a second push to watch the comments update in place. That logic is unchanged from main and runs daily in the lecture repos.

Release. Per decision 4 on #110, the release carrying this is staged: exact tag first, canary ci.yml PR against it, then v0.

Open points

  • npm allowScripts warning. npm 11.19, the containers' npm, warns on every install that N packages have install scripts not covered by allowScripts. The scripts still run. If npm 12's strict default ever lands in a bundled Node, name-only approvals in package.json would keep today's behaviour. I left that out until it is needed.
  • From the Cloudflare runs (neither is a defect of this PR):
    • Pages answers …/lectures/intro.html with a 308 to the extension-less path, so the PR comment's per-lecture links work through one redirect. Linking the extension-less path would skip the redirect, as a possible follow-up.
    • wrangler 4.136.3 hands pages project create / pages deploy over to a Workers deployment when it detects an AI-agent environment, the Pages project does not exist yet, and --force is absent (src/pages/delegate-to-workers.ts).
      • GitHub Actions is not an agent environment, and the handover never fires once the project exists, so CI is unaffected.
      • Anyone driving wrangler from an agent shell against a new project should create it first, with --force.

Refs #105 (closes it, with #170 already merged), PLAN item 8. Tracking: #110.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh

… the Netlify token off argv (#105)

Surface deploy failures (preview-cloudflare). Composite bash steps run
under `bash -eo pipefail`, so `DEPLOY_OUTPUT=$(wrangler pages deploy …
2>&1)` aborted the step as soon as wrangler failed, with wrangler's
stderr captured into the variable. The log ended at "Deploying
preview…", and the dump, the error branch and `DEPLOY_EXIT_CODE=$?`
after it were all dead code. wrangler now runs with `set +e` around
`2>&1 | tee "$LOG"` inside the Deployment Output group, the exit code
comes from PIPESTATUS[0], and a failure ends with an ::error::
annotation and wrangler's own exit code. DEPLOY_OUTPUT is read back from
the log, so the deployment-url extraction is unchanged. A plain
`… | tee; EXIT=${PIPESTATUS[0]}` would still abort before EXIT= under
pipefail; that is why `set +e` is there.

Surface deploy failures (preview-netlify). The same abort-before-dump
shape discarded the --json error payload. stdout, and only stdout, now
goes through tee to a file with the same PIPESTATUS capture and
::error::. stderr stays on the log: merging it would corrupt the JSON on
a successful deploy that prints an npm or Node notice. The URL parse is
now `|| true`. Before, a non-JSON stdout made python3 exit non-zero and
set -e aborted the step at the assignment, so the "Raw output was:"
guard only ever fired on valid JSON lacking deploy_url/url. The guard
now also emits an ::error::. --json output has no trailing newline, so
the line is ended before ::endgroup:: and ::error::, which the runner
reads only at the start of a line.

Pin the CLIs. Both actions ran `npm install -g <cli>@latest` and then
handed the CLI the deploy token, in a repo that SHA-pins every
third-party Action. Each action directory now has a private package.json
pinning the CLI exactly (wrangler 4.136.3, netlify-cli 27.8.1) and a
lockfileVersion 3 package-lock.json. Both were generated on linux-x64
with Node 24.21.0 / npm 11.19.0, the containers' Node, and the wrangler
lock carries the @cloudflare/workerd-linux-64 and @esbuild/linux-x64
optional deps. The install step (id install-cli, same check-trust gate)
copies both files into a fresh mktemp dir, not $GITHUB_ACTION_PATH,
because in a container job that is the _actions dir mounted from the
host. It then runs `npm ci --no-audit --no-fund` with install scripts
left on, checks that `<cli> --version` runs and prints it, outputs the
absolute binary path as `bin`, and adds node_modules/.bin to GITHUB_PATH
so the CLI stays on PATH for later caller steps, as the global install
left it. The deploy steps call the CLI by that absolute path. A new
Dependabot npm entry covers both directories, grouped the same way as
the other ecosystems.

Keep the Netlify token off argv. `--auth="${{ inputs.netlify-auth-token
}}"` put the token into the step script the runner writes to disk and
into the netlify process's command line. The step now has an env: block:
NETLIFY_AUTH_TOKEN and NETLIFY_SITE_ID, which netlify-cli 27.8.1 reads
natively (getToken() falls back to NETLIFY_AUTH_TOKEN, and `deploy
--site` defaults to NETLIFY_SITE_ID, checked in the installed source),
so --auth and --site are dropped. The PR number, head SHA and build-dir
move into env: too, so the run: block has no ${{ }} left. The alias and
message are unchanged.

A successful deploy behaves as before apart from the pinned CLI version
and where it is installed. The READMEs' Requirements sections name the
pin and the npm ci / registry.npmjs.org requirement. The Netlify
README's stale "jq" line is corrected to python3, which the action has
used since 0.5.1. Closes PLAN.md backlog item 8 (PLAN.md itself is
left to the PR that owns it).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh
The preview actions cannot run in the harness: a deploy needs the
provider's token, and the actions skip Dependabot's PRs outright. So
without some job here, the new Dependabot npm bumps of wrangler and
netlify-cli would merge with no CI signal at all.

preview-cli-install sets up Node 24 with actions/setup-node@v7 (the
Node the READMEs tell hosted-runner callers to use, and the containers'
major). For each preview action it copies package.json and
package-lock.json into a temp dir, runs `npm ci --no-audit --no-fund`,
then requires `<cli> --version` to run and to report the version pinned
in package.json. It proves the lockfile installs on a clean runner and
the CLI starts. It does not run the actions' own install step and cannot
tell whether a new CLI still deploys.

The job fits the existing harness shape:
- It is gated on needs.gate.outputs.relevant like every other job. A
  finer "only when preview files change" condition would break
  harness-summary's all-ran / all-skipped certification.
- It is added to harness-summary's needs.
- The gate's self-test protects the two lockfiles as must-run paths.
  They are listed by hand next to the fixture, because the job has no
  `uses: ./` line to derive them from.

TESTING.md's coverage table gains a row for this. The Dependabot entry
names the job as the npm PRs' only CI signal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh
Review follow-up. Adding node_modules/.bin to GITHUB_PATH prepended every
dependency bin of the CLI (about 60 for netlify-cli: esbuild, tsc,
semver, nft, ...), shadowing same-named tools in the caller's later
steps. The old global install exposed only netlify/ntl and
wrangler/wrangler2/cf-wrangler. Those are now linked into a bin/
directory and only that is added. Also rewords the existing Node 24
CHANGELOG entry, which still called the CLIs @latest.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Copilot review overview

🔵 Needs a closer look

It is an explicit Draft whose deploy code paths cannot be exercised by CI and require a real preview deploy on each provider with live secrets before it can be safely approved.

Review effort: Balanced
Findings: None

What changed in this PR

This PR is the code half of #105, hardening the two PR-preview composite actions (preview-cloudflare, preview-netlify) along three axes: making failed deploys visible, pinning the deploy CLIs, and keeping the Netlify token out of the process argv/step script. It fits into the repo's broader July-2026 maintenance audit (#110) and its existing discipline of SHA-pinning third-party dependencies and surfacing CI failures.

Changes:

  • Surface deploy errors: both actions now stream CLI output through tee, capture the real exit code via PIPESTATUS (with set +e/set -e around the pipeline so the composite bash -eo pipefail shell can't abort before the code is read), and emit ::error:: annotations on failure. The Netlify JSON parse is made non-fatal (|| true) so the raw-output guard can finally fire.
  • Pin the CLIs by lockfile: each action gains a package.json/package-lock.json pinning wrangler 4.136.3 / netlify-cli 27.8.1, installed per-job with npm ci into a temp dir; a new npm Dependabot entry keeps them current, and a preview-cli-install harness job gives Dependabot bumps some CI signal.
  • Netlify token off argv: the auth token and site move into env: (NETLIFY_AUTH_TOKEN/NETLIFY_SITE_ID), dropping --auth/--site.
File Description
preview-cloudflare/​action.yml Rewrites CLI install (pinned npm ci + bin output/PATH) and the deploy capture to tee+PIPESTATUS with ::error:: on failure.
preview-netlify/​action.yml Same install/error-surfacing rewrite, moves token/site/PR inputs into env:, drops --auth/--site, makes the JSON parse non-fatal.
preview-cloudflare/​package.json /​ package-lock.json Pins wrangler 4.136.3 with a lockfileVersion-3 lock (integrity hashes, linux optional deps).
preview-netlify/​package.json /​ package-lock.json Pins netlify-cli 27.8.1 with an equivalent committed lock.
.github/​dependabot.yml Adds an npm ecosystem entry for both preview dirs using the file's two-group (minor/patch + major) convention.
.github/​workflows/​test-actions.yml Adds preview-cli-install job (install + version check), wires it into the gate must-run list and harness-summary.
preview-*/​README.md, TESTING.md, CHANGELOG.md Document the pin, npm ci requirement, Dependabot, the harness coverage, and correct Netlify's stale jq→python3 note.

I reviewed the shell control flow (tee/PIPESTATUS/set +e), the temp-dir install and bin/ symlink-to-GITHUB_PATH logic, the step if:/output dependencies, the lockfile pins, the Dependabot grouping, and the harness gate/certification interaction. These are internally consistent, and the PR's own "Open points" already acknowledge the residual tradeoffs (--no-build token inheritance, /tmp accumulation, README version numbers going stale), so I have not re-raised them.

Files not reviewed (1)
  • preview-cloudflare/package-lock.json: Generated file

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

mmcky added a commit that referenced this pull request Sep 23, 2026
…with the shipped code (#106, #109, #99) (#175)

* docs: sweep to the 2026.06 baseline and measured image sizes (#106)

Both images ship anaconda=2026.06 (containers/quantecon/environment.yml:11;
the lean image carries the matching pin set), but seven sites still said
2025.12. They now say 2026.06.

Image sizes were a mix of round "~8GB / ~3GB" figures, a "~60% smaller"
claim, and an older measured pair. Every size site now carries the pair the
fixed size job (#172) produced on 2026-09-23, run 35856865426 (Docker 28.0.4,
overlay2, ubuntu-latest), and says which metric it is:

- quantecon (full): 3.33 GB compressed (what a cold pull downloads),
  8.60 GB on disk
- quantecon-build (lean): 2.93 GB compressed, 7.33 GB on disk

The lean image is about 12% smaller to pull and 15% smaller on disk, so the
"faster CI pulls" / "fast image pulls" wording becomes "a modestly smaller
pull", and the lean README's unmeasured pull-time and package-count rows go.

"Minimal TexLive" was false. The two Dockerfiles' apt lists differ in exactly
two packages: the lean image drops texlive-luatex and adds graphviz;
texlive-latex-extra and texlive-fonts-extra are in both. The docs now say so,
and name what actually distinguishes the lean image: no anaconda
metapackage, an explicit package list pinned to the 2026.06 baseline. The
full image's "Complete TexLive installation" is corrected to match.

CHANGELOG history and PLAN.md:68's narration of the old date-pin keep their
2025.12 mentions on purpose.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh

* docs: reconcile READMEs, guides and templates with the shipped code (#109, #99)

The docs half of #109, with #99 folded in. The code items (the
build-jupyter-cache latex-requirements-file passthrough, the cname warning
and the template pin-drift check) ride with #107's PR.

Examples that failed for adopters:
- permissions: the preview-netlify and preview-cloudflare "Complete Workflow
  Example" blocks declared none, and the root README and QUICK-REFERENCE
  container quick starts declared contents/packages only. Both preview
  actions list, create and update PR comments through
  github.rest.issues.* with github.token, so each block now grants
  contents: read and pull-requests: write.
- actions/checkout: the remaining 29 @v4 and 2 @v5 references across 13
  docs move to @v7, matching the templates (#168) and this repo's
  workflows. with: fetch-depth lines are kept.

Documented behaviour that does not exist:
- QUICK-REFERENCE: the "Preview with Custom URL" recipe passed an alias
  input preview-netlify does not accept (the alias is fixed at pr-N); it
  becomes a short "Preview URL" note. The setup-environment key row now
  carries the environment-name and python-version segments and the cached
  path. The sample log block's "LaTeX cache hit" line (no LaTeX caching
  exists) and its other invented lines are replaced by strings the actions
  actually print. The "Pages 404?" snippet recommended contents: write,
  which as a permissions block would also drop pages and id-token; it now
  lists pages: write and id-token: write, with contents: write only for
  create-release-assets (#99).
- MIGRATION-GUIDE: the collab.yml snippet passed build-html and
  cache-workflow, which build-lectures never accepted; it now restores the
  cache with restore-jupyter-cache and builds with builder/source-dir. The
  copied commit message no longer claims LaTeX caching, and the
  build-jupyter-cache key carries its update-hash segment here and in
  ARCHITECTURE (#99).
- build-lectures README: "use setup-latex" pointed at a removed action; the
  inputs table gains the missing failure-artifact-name row.
- README and ARCHITECTURE said restore-jupyter-cache "never saves"; it is
  read-only by default with an optional PR-scoped save-cache.
- setup-environment README: the cache key and path now match action.yml.

Templates and the custom domain:
- The Actions Pages deploy ignores a CNAME file, so the cname input has no
  effect. templates/publish.yml, templates/README.md, MIGRATION-GUIDE and
  QUICK-REFERENCE now point at Settings -> Pages instead of offering cname.
- templates/publish.yml's release-asset block now says it needs a tag
  trigger (the file runs on pushes to main and manual dispatch) and
  contents: write (the job grants contents: read).
- New templates/latex-requirements.txt: the TeX packages the two images
  share, in the whole-line-comment format setup-environment parses. The
  cache.yml standard-runner comment and templates/README point at it, since
  a standard-runner pdflatex build fails without the file.
- cache.yml and templates/README describe the _build artifact as
  failure-only, which it has been since v0.8.0.

Smaller items: the lean image README's last @main example moves to @v0;
the full image README's theme version reads 0.21.0, the environment.yml
pin. README's Contributing section now points at CONTRIBUTING.md, which
tests by branch and moves v0; CONTRIBUTING gains the staged-release
procedure decided on #110 (decision 4), its known limits and the rollback.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh

* docs: bring PLAN.md, CONTRIBUTING and the CHANGELOG up to date (#106, #109)

PLAN.md:
- The consumers table said five lecture repos were pinned to v0.8.0 or
  v0.9.0. Dependabot bumped all six exact call sites to v0.11.1 between
  2026-08-12 and 2026-08-24 (#110's 2026-09-23 revalidation; the pins are
  confirmed by code search). The rows, the "Corrected" note and the
  lecture-jax rollout row now say so; the section keeps its structure.
- The August triage table already had rows for the issues #106 lists,
  except #135. Each row is refreshed to its state on 2026-09-23 (all are
  open; the open PRs #144, #170, #171 and #172 and the in-progress #105 and
  #107 work are named), and #135 gets a row. No rows are duplicated.
- Item 10's "propagate corrected container-size figures" half is marked
  done by this sweep; the trim itself stays open as its own PR (decision 1
  on #110).
- The "Last updated" line records this pass.

CONTRIBUTING.md: the doc-update matrix gains a PLAN.md row, so a backlog
item or consumer ref that moves updates the plan rather than waiting for
the next audit.

CHANGELOG.md: one [Unreleased] Documentation entry for the sweep.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh

* docs: address review of the #106/#109 docs sweep

- templates/latex-requirements.txt: describe the file format so it holds
  under both the current parse (grep -v '^#') and #173's, where '#' starts
  a comment anywhere. Drop the claim that an inline '#' reaches apt-get.
- templates/publish.yml: the release-asset note lists a third change, the
  tag pattern under the github-pages environment's deployment branches
  and tags, which otherwise reject a tag-triggered run.
- CONTRIBUTING.md: the staged-release limits say that steps 2-3 run
  neither publish-gh-pages (the canary's publish.yml fires only on a
  publish* tag) nor setup-environment at the candidate ref, replacing the
  narrower release-asset bullet.
- PLAN.md: #172 is marked open with the run the sizes come from; #144
  needs a rebase before review.
- CHANGELOG.md: the 2026.06 baseline is the full image's metapackage and
  the lean image's pin set, not something both images ship.
- containers/README.md: the lean image carries the pinned science stack,
  so "Jupyter Book build tools only" loses "only".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh

* docs: address the second review round of the #106/#109 sweep

- Four more job examples call preview-netlify without a permissions
  block (MIGRATION-GUIDE's preview job, QUICK-REFERENCE's standard CI
  workflow, both ARCHITECTURE workflows). Each now grants contents: read
  and pull-requests: write (plus packages: read where it pulls the
  image), so the CHANGELOG line saying preview examples grant
  pull-requests: write is true of every one.
- README's publish-gh-pages feature line no longer lists custom-domain
  support first; custom domains are set in Settings -> Pages.
- MIGRATION-GUIDE's sample commit message says "conda environment
  caching": there is no separate pip cache.
- PLAN.md's #105 and #107 rows cite the now-open #174 (draft) and #173.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh

* docs(templates): list make in the example latex-requirements.txt

Copilot review on #175. The header says the file lists the TeX packages
and build tools both images install, but omitted make, which both
Dockerfiles install under "Build tools". It is needed, not incidental:
jupyter-book 1.0.4.post1's pdflatex builder runs `make all-pdf` in the
LaTeX output directory (jupyter_book/cli/main.py). Hosted Ubuntu runners
ship make already, so on them this is a no-op install; on a minimal
runner it is the difference between a PDF and a failed build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh

* docs(plan): #170 has merged

Refresh the #105 disposition row now that the README warning is on main.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh

* docs(containers): theme version is now 0.22.0

#162 moved both images to quantecon-book-theme 0.22.0 (full pins ==0.22.0,
lean >=0.22.0) after this sweep set the full image's README to 0.21.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh

* docs: add the .fr consumer row and refresh the current-release lines (#106, #109)

lecture-python-programming.fr exact-pins preview-netlify and publish-gh-pages
(with create-release-assets) at v0.11.1, moved there from v0.8.0 by Dependabot
on 2026-09-23, so it joins the consumers table and the exact-pin count becomes
eight call sites across six repos.

README.md and copilot-instructions.md said the current release was v0.8.0; it
is v0.11.1.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs(plan): carry the .fr row into the consumer counts

d1b8fb1 added lecture-python-programming.fr (two exact @v0.11.1 call
sites, including publish-gh-pages). Two counts elsewhere in PLAN.md still
predated it: the Last-updated line said all six exact pins, and the
lecture-progress note had publish-gh-pages at 7/7 with five exact. They
now read eight pins across six repos, and 8/8 with six exact.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh

* docs: lean image is 7.32 GB on disk after the #162 rebuild

The first size report on main (run 35930060129, after #162 rebuilt both
images with quantecon-book-theme 0.22.0) reads full 3.33 GB compressed /
8.60 GB on disk, unchanged, and lean 2.93 GB / 7.32 GB: the lean on-disk
figure dropped by about 5 MB, enough to move the second decimal. The
eleven sites that quoted 7.33 now say 7.32, and PLAN.md's #106 row cites
that main run instead of the earlier branch dispatch. The ~15% (on disk)
and ~12% (compressed) gaps still hold.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DwQrz9VbFrbAD7uh2LTgzh

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Matt McKay <mmcky@users.noreply.github.com>
mmcky and others added 2 commits September 24, 2026 10:48
…ploy

Resolves the conflicts with #176: test-actions.yml keeps the four
deploy-cloudflare harness jobs and this branch's preview-cli-install job,
with all five in harness-summary's needs; TESTING.md keeps the
deploy-cloudflare row and this branch's split of the preview-* and
publish-gh-pages rows.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
…--no-build for netlify

- The CLI install lands in a fresh directory under RUNNER_TEMP, which the runner
  clears between jobs, instead of mktemp's /tmp, where it accumulated on a
  persistent self-hosted runner. Same place deploy-cloudflare uses.
- The npm Dependabot entry deploy-cloudflare introduced now lists the two preview
  directories too, so one PR carries all three CLI bumps instead of two entries
  racing each other.
- netlify deploy passes --no-build: the site is prebuilt, and netlify-cli 27
  would otherwise run any configured build command first, in a process that
  inherits NETLIFY_AUTH_TOKEN.
- The READMEs no longer quote a version number that the first bump would date;
  package.json is the source.
- Every unquoted $GITHUB_OUTPUT redirect in both actions is quoted.

Verified locally: shellcheck is clean at every severity on the four changed
run: blocks; both install steps run from their lockfiles under a scratch
RUNNER_TEMP, report 4.136.3 and 27.8.1, and expose only the CLIs' own
executables; the Cloudflare deploy step with a bogus token prints wrangler's
error inside the group and ends with the ::error:: annotation and exit 1.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@mmcky

mmcky commented Sep 24, 2026

Copy link
Copy Markdown
Contributor

Two pushes to bring this up to date after #176 landed and to fold in the review nits, ahead of the real-deploy validation.

3cc10ff merges main. The conflicts were with #176: test-actions.yml keeps the four dc-* jobs and preview-cli-install, all five in harness-summary's needs, and TESTING.md keeps the deploy-cloudflare row plus this PR's split of the preview and publish-gh-pages rows.

544b4b6 applies the nits: the install lands under RUNNER_TEMP (mktemp -d "$RUNNER_TEMP/preview-cloudflare.XXXXXX"), where deploy-cloudflare already installs and which hosted runners clear between jobs; the npm Dependabot entry that #176 introduced now lists all three CLI directories instead of a second entry; netlify deploy gets --no-build; the READMEs stop quoting a version number; and every $GITHUB_OUTPUT redirect is quoted.

Verified on this machine: shellcheck clean at every severity on the four changed run: blocks; both install steps run from their lockfiles under a scratch RUNNER_TEMP, report 4.136.3 and 27.8.1, and link only the CLIs' own executables (esbuild stays hidden); and the Cloudflare deploy step with a bogus token prints wrangler's Authentication failed [code: 9106] inside the output group, closes the group, and ends with ::error::wrangler pages deploy failed (exit 1) and no outputs. Next is the real deploy against a throwaway Pages project on the QuantEcon account.

Assisted-by: Claude Code (Claude Fable 5.1)

@mmcky

mmcky commented Sep 24, 2026

Copy link
Copy Markdown
Contributor

Real Cloudflare deploy done from this machine, through the action's own deploy step (extracted verbatim from preview-cloudflare/action.yml at 544b4b6), against a throwaway Direct Upload project qe-preview-canary on the QuantEcon account, on wrangler 4.136.3 from the committed lockfile.

Happy path. Two deploys for PR 999 with different commit SHAs. Both exited 0, wrangler's output streamed inside the Deployment Output group, and the outputs came out as documented: deploy-url=https://pr-999.qe-preview-canary.pages.dev both times, deployment-url a different hash URL each time (4b67fdb2… then 76164830…), so the "drop the alias, keep the hash" extraction works with a wrangler that prints both. The alias serves the newer build, each hash URL still serves its own build. One observation, not a defect of this PR: Pages answers a …/lectures/intro.html link with a 308 to the extension-less path, and following it gives 200 via 1 redirect(s) to https://pr-999.qe-preview-canary.pages.dev/lectures/intro, so the per-lecture links in the PR comment work through one redirect.

Failure path. Same step with a bogus token: wrangler's Authentication failed (status: 400) [code: 9106] inside the group, the group closed, then ::error::wrangler pages deploy failed (exit 1) and no outputs written. On main this run ends silently after "Deploying preview".

Finding worth knowing. wrangler 4.136.3 delegates pages project create and pages deploy to Workers, creating a Worker with static assets instead, when all three hold: it detects an AI-agent environment, the target Pages project does not exist yet, and --force is absent (src/pages/delegate-to-workers.ts). GitHub Actions is not an agent environment, so the action is unaffected in CI, and once the project exists the delegation never fires. It did fire on my first attempt from an agent shell and created a Worker qe-preview-canary, since deleted. Anyone driving wrangler from Claude Code or similar against a not-yet-created project should create the project first, with --force.

Still to run: the same deploy from the canary repo's ci.yml on a same-repo PR, which needs an API token in that repo's secrets, and the Netlify half. The Pages project is deleted once those are done.

Assisted-by: Claude Code (Claude Fable 5.1)

@mmcky

mmcky commented Sep 24, 2026

Copy link
Copy Markdown
Contributor

Both providers exercised for real from a same-repo canary PR, QuantEcon/test-actions-lecture-intro#65, running this branch's actions in the quantecon-build container (run 35950081155).

preview-cloudflare. npm ci from the lockfile landed under /__w/_temp/preview-cloudflare.XXXXXX in the container and reported wrangler 4.136.3. The deploy uploaded 173 files to the throwaway qe-preview-canary project; wrangler's output streamed inside the Deployment Output group; the step printed the stable https://pr-65.qe-preview-canary.pages.dev and the pinned https://01c6f2ca.qe-preview-canary.pages.dev; the "☁️ Cloudflare Preview Ready!" comment carries both, and the alias serves the built site (intro.html answers 200 through Pages' one .html redirect). No changed-lecture links, correctly, since the PR touched only ci.yml.

preview-netlify. npm ci from the lockfile on the container's Node 24.21.0 reported netlify-cli 27.8.1. The deploy ran with --no-build, with NETLIFY_AUTH_TOKEN and NETLIFY_SITE_ID arriving as masked environment variables and nothing on argv; the --json result parsed to https://pr-65--jade-tarsier-d98a19.netlify.app, and the "📖 Netlify Preview Ready!" comment posted.

Failure path, in CI. The first run of that PR went out with the token secret empty (a secret-name mismatch on the org side, since fixed): wrangler's "In a non-interactive environment, it's necessary to set a CLOUDFLARE_API_TOKEN" appeared inside the group, the group closed, ::error::wrangler pages deploy failed (exit 1) fired, and the job went red visibly. On main that run ends silently after "Deploying preview".

Not re-run: a second push to check the comments update in place. That logic is unchanged from main and exercised daily by the lecture repos, and the alias tracking the newest deployment was proven locally earlier in this thread.

That covers everything under What still needs a human, so this leaves draft. Release stays staged per decision 4 on #110.

Assisted-by: Claude Code (Claude Fable 5.1)

@mmcky
mmcky marked this pull request as ready for review September 24, 2026 03:11
@mmcky
mmcky merged commit 7a40cd4 into main Sep 24, 2026
25 checks passed
@mmcky
mmcky deleted the claude/105-preview-deploy branch September 24, 2026 03:22
@mmcky mmcky mentioned this pull request Sep 24, 2026
mmcky pushed a commit that referenced this pull request Sep 25, 2026
…PLAN item 15 (#187)

* docs(plan): refresh after v0.12.0 closed the July 2026 audit; finish PLAN item 15

v0.12.0 delivered the rest of the #110 audit (#105-#109, #99), so the plan
catches up:

- Current state: eight actions, v0.12.0 is the latest release and v0 points
  at it (a53dbe4); a close-out bullet for the audit and its staged release.
- Consumers: the two follow-ups outside this repo. Six consumers still pass
  publish-gh-pages' cname (now a warning, no effect), and the canary should
  gain a permanent preview-cloudflare step against qe-preview-canary.
- Backlog: items 7 (asset-url) and 8 (Netlify token into env:) done; item 5's
  note that the wrangler capture was still fatal is resolved by #174; item 10
  absorbed by the user manual (#178); item 13 drops a stale "no open PRs";
  item 15 records what is done and keeps #107's --path-output residual; new
  item 18 records the ${{ }} expressions still expanded inside run: scripts.
- Dispositions: #105-#109, #99 and #110 closed; #135's staging note
  generalised to any release that changes action behaviour.

PLAN item 15's last two small fixes:

- scripts/check-latex-versions.sh runs under set -euo pipefail, so a failed
  apt-get update fails the run instead of reporting from a stale index. The
  per-package lookup keeps || true: grep exits 1 for a package apt does not
  know, which under pipefail would abort before the NOT FOUND branch.
- restore-jupyter-cache/README.md's status sample matches the action's
  output: no "Age Information" block (never printed), the "Directory Sizes"
  block it does print, the "Save Cache" line, and the Cache Hit / Matched Key
  shape of a read-only prefix restore.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gmq1LGR87Md5rq4RJshmMp

* docs(plan): apply review corrections to the v0.12.0 refresh

- PLAN: the exact pins are a release behind since v0.12.0; only
  lecture-python.myst (on @v0) sees the cname warning today; the canary can
  test a candidate when staged by hand; item 18 lists every caller-supplied
  input still expanded in run: (adds html-copy-pdf, html-copy-notebooks,
  save-cache); item 14's `||` is escaped so its row stops splitting; the
  dispositions header says which rows were updated when.
- restore-jupyter-cache README: the sample's sizes and file count add up,
  du prints 6.0M, placeholders match the README's {env-hash} notation, and
  the prose qualifies the never-exact claim to the generated key and says
  the report's Cache Hit is actions/cache's exact-match flag, not the
  action's cache-hit output.
- CHANGELOG: "delivered" rather than "closed", and the LaTeX script gains
  (not keeps) its `|| true`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gmq1LGR87Md5rq4RJshmMp

* docs: reference #187 in PLAN item 15 and the new CHANGELOG entries

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gmq1LGR87Md5rq4RJshmMp

---------

Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants