Repository navigation
feat(setup-latex): install TeX Live from a cache of the downloaded packages (#224) - #283
Conversation
…ckages (#224) A new action, setup-latex, installs the apt packages it is given and keeps their downloaded .deb archives in the repository's Actions cache. The key hashes the installed package set, so an exact hit installs the archives as local files with no apt-get update and no download; a fallback restore or a miss downloads only what the cache lacks, prunes, and saves. A download-timeout-minutes limit (default 30) stops a mirror that trickles. The work is in scripts/latex-packages.sh, which setup-environment's install-latex will share. Part of #224. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev
…s and the example list's header (#224) ARCHITECTURE.md's parts table counts nine actions, and its shared scripts row names the cached LaTeX install. security.md lists packages among the inputs that may span lines. The example latex-requirements.txt names setup-latex, and its format note now matches the parser: '#' starts a comment anywhere on a line. Part of #224. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev
Brings in #280. The CHANGELOG's [Unreleased] keeps both entries, setup-latex's ### Added above #280's ### Changed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev
apt fails at once a response whose length it knows to be wrong: a 1 GB InRelease is past its 10 MB limit, and a .deb's must match the index. With no length, apt reads until the connection closes, which the stand-in never does, so only download-timeout-minutes stops it. Part of #224. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev
…from a mirror (#224) Two things a runner showed. apt refuses even local .deb files under --no-download, so the completeness check always failed and every hit went online. And given a local file whose version the image's lists also carry, apt downloads that version from a mirror rather than read the file. With the cache as apt's Dir::Cache::archives, it finds each archive there and fetches nothing; a version only the file carries is read in place. The check is now apt's --print-uris, which lists what it would fetch and reads no mirror. Part of #224. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev
apt failed at once both a 1 GB length, past its 10 MB InRelease limit, and a response with no length, so apt-get update never hung. Part of #224. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev
…prune's says what it removes (#224) Part of #224. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev
Brings in #281. No conflict: the CHANGELOG's [Unreleased] keeps setup-latex's ### Added first, then #280's ### Changed and #281's ### Fixed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev
There was a problem hiding this comment.
Note
Copilot was unable to complete this review at the selected tier due to model policy or plan restrictions.
🟢 Approval recommended
The new setup-latex composite action is delivered as a self-contained addition with shared installer logic, documentation updates, and CI harness coverage, and the provided context does not identify any open blockers preventing approval.
No open issues 🎉
What changed in this PR
This pull request adds a new composite GitHub Action, setup-latex, that installs TeX Live (and other apt packages) using a cache of downloaded .deb archives to avoid repeated large downloads and mitigate slow Ubuntu mirrors. It includes a shared installer script intended for reuse in a follow-up PR, plus harness coverage and documentation.
Changes:
- Introduces
setup-latexcomposite action with cache restore/save, exact-hit vs fallback vs miss install behavior, and an optional download timeout. - Adds
scripts/latex-packages.shto parse/validate package lists, compute cache keys, manage the apt archive cache directory, and drive the install flow. - Expands CI harness with fixtures to prove “no mirror contacted” on exact hits, validate fallback behavior, and enforce timeout behavior; updates docs/templates/changelog accordingly.
- Review notes to address: improve error reporting when prerequisites are missing (clear
::error::messaging ifsudoisn’t available / not passwordless when required; and if thetimeoututility is missing whendownload-timeout-minutes > 0).
| File | Review focus / notes |
|---|---|
templates/latex-requirements.txt |
Template header and format notes updated to match the new parser behavior and setup-latex usage. |
setup-latex/README.md |
Generated README signposting the new action documentation. |
setup-latex/action.yml |
New composite action wiring input validation, container detection, cache restore/save, and install via the shared script. |
scripts/latex-packages.sh |
Core implementation (list parsing/validation, keying, cache dir setup, install logic, timeout handling). Needs clearer prerequisite checks/messages for missing sudo and missing timeout. |
scripts/generate-docs.py |
Adds setup-latex into the generated docs ordering. |
docs/user/security.md |
Documents setup-latex’s multiline packages input alongside other line-break-safe inputs. |
docs/user/README.md |
Adds setup-latex to the user-manual action index. |
docs/user/actions/setup-latex.md |
New user documentation chapter covering behavior, keying, timeout guidance, and troubleshooting. |
docs/dev/TESTING.md |
Documents harness coverage for the new action. |
docs/dev/ARCHITECTURE.md |
Updates the architecture “parts” table to include setup-latex and the shared LaTeX caching script. |
CHANGELOG.md |
Adds an [Unreleased] entry describing the new setup-latex action. |
.github/workflows/test-actions.yml |
Adds latex-* harness jobs (seed/hit/fallback/timeout/inputs) and a line-break hardening case. |
.github/fixtures/setup-latex/check-tex.sh |
Fixture script verifying packages are configured and pdflatex works (including trigger effects). |
.github/fixtures/setup-latex/apt-proxy.py |
Fixture proxy to refuse/record requests (prove offline hit) and trickle indefinitely (exercise timeout). |
This pull request requires changes.
Review effort: Balanced
#224) From Copilot's review of #283. On a self-hosted runner whose user cannot sudo without a password, prepare now fails before it makes anything, with an ::error:: that says apt needs root and how to give it, instead of sudo's own message. latex-inputs runs prepare with a sudo stub that asks for a password, and checks the message. Part of #224. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev
|
On the two notes in Copilot's review summary:
Claude Code (on behalf of mmcky) |
Brings in #283's sudo check (e4bb43a). TESTING.md keeps this branch's setup-environment row and #283's setup-latex row. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev
Brings in #283's squash, d89b021, whose tree is that of e4bb43a, which this branch already holds. Where the two touch the same lines, this branch's version, which builds on e4bb43a, is kept: the tree is unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev
…e cache, as setup-latex does (#224) (#284) * feat(setup-latex): install TeX Live from a cache of the downloaded packages (#224) A new action, setup-latex, installs the apt packages it is given and keeps their downloaded .deb archives in the repository's Actions cache. The key hashes the installed package set, so an exact hit installs the archives as local files with no apt-get update and no download; a fallback restore or a miss downloads only what the cache lacks, prunes, and saves. A download-timeout-minutes limit (default 30) stops a mirror that trickles. The work is in scripts/latex-packages.sh, which setup-environment's install-latex will share. Part of #224. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev * docs(setup-latex): the CHANGELOG entry, TESTING row, ARCHITECTURE rows and the example list's header (#224) ARCHITECTURE.md's parts table counts nine actions, and its shared scripts row names the cached LaTeX install. security.md lists packages among the inputs that may span lines. The example latex-requirements.txt names setup-latex, and its format note now matches the parser: '#' starts a comment anywhere on a line. Part of #224. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev * ci(harness): the trickling stand-in sends no Content-Length (#224) apt fails at once a response whose length it knows to be wrong: a 1 GB InRelease is past its 10 MB limit, and a .deb's must match the index. With no length, apt reads until the connection closes, which the stand-in never does, so only download-timeout-minutes stops it. Part of #224. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev * fix(setup-latex): install an exact hit from the cache directory, not from a mirror (#224) Two things a runner showed. apt refuses even local .deb files under --no-download, so the completeness check always failed and every hit went online. And given a local file whose version the image's lists also carry, apt downloads that version from a mirror rather than read the file. With the cache as apt's Dir::Cache::archives, it finds each archive there and fetches nothing; a version only the file carries is read in place. The check is now apt's --print-uris, which lists what it would fetch and reads no mirror. Part of #224. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev * ci(harness): the trickling stand-in says it is 5 MB long (#224) apt failed at once both a 1 GB length, past its 10 MB InRelease limit, and a response with no length, so apt-get update never hung. Part of #224. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev * fix(setup-latex): the timeout's message says minute for one, and the prune's says what it removes (#224) Part of #224. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev * feat(setup-environment): install-latex installs from the LaTeX package cache, as setup-latex does (#224) install-latex now runs scripts/latex-packages.sh, as setup-latex does: an exact hit installs the cached archives with no apt-get update and no download; a fallback restore or a miss downloads what the cache lacks, within a fixed 30 minutes, and saves straight after the install. A new output, latex-cache-hit, says which. cache-version keys the LaTeX cache too. The list's entries must be apt package names. The harness gains env-latex-seed and env-latex-hit, the hit behind the refusing stand-in. The stand-in's setup moves into refuse-mirrors.sh, which latex-hit now uses too. PLAN.md drops #224. Part of #224. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev * fix(setup-latex): say why when the job's user has no passwordless sudo (#224) From Copilot's review of #283. On a self-hosted runner whose user cannot sudo without a password, prepare now fails before it makes anything, with an ::error:: that says apt needs root and how to give it, instead of sudo's own message. latex-inputs runs prepare with a sudo stub that asks for a password, and checks the message. Part of #224. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev * ci(harness): fail clearly when the apt stand-in never starts; the summary claims no download it cannot know (#224) From Copilot's review of #284. refuse-mirrors.sh and latex-timeout now fail, with the stand-in's output, when it is not listening after 10 s, instead of blaming the mirrors later. setup-environment's summary says an exact cache match, not 'no download', since the rare exact match that falls short downloads, with a warning in the install step. Part of #224. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Brings in #280, #281, #283 and #284. CHANGELOG keeps main's [Unreleased] entries and puts #142's in Changed; PLAN keeps main's rows and drops #142 from the Container validation row. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMZzgrBo6FK6GsstoUY
* release: v0.17.0 Cut [0.17.0] - 2026-11-10 under an empty [Unreleased]: setup-latex (#283), setup-environment's install-latex on the LaTeX cache (#284), the execution cache keyed on the environment and the templates restoring it (#280), preview-cloudflare's deploy-url (#281), and :latest promoted only after the smoke test (#274). PLAN's release line: 9 actions with setup-latex, v0.17.0 the latest release, @v0 on v0.16.0 until this release's canary and the lecture matrix have passed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMbZoC2dpGt3sPyBjyd * docs(plan): format the release line's v0.17.0 as code, as its other versions are Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WT8bMbZoC2dpGt3sPyBjyd --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
A plain
apt-get installdownloads TeX Live from the Ubuntu mirror the runner is given, on every run: 141 packages and 1077 MB for lecture-python-advanced.myst's list on the 26.04 image. A slow mirror trickles that at 60–700 kB/s without ever failing, so the build simply runs on. Since 2026-09-01, 12 of 220 such steps in the lecture repositories took over 5 minutes, and the slowest ran for nearly 6 hours (the numbers are in the issue check on #224). The 26.04 runner image fails over to another mirror when one stops answering for 15 seconds, but not when one answers slowly.This PR is the first of the two the maintainer chose on #224: a new action,
setup-latex, which nothing calls yet, so it can merge before Monday's lecture-matrix run. The second movessetup-environment'sinstall-latexonto the same script and cache, and waits for that run.setup-latexinstalls the apt packages it is given, and keeps their downloaded.debarchives in the repository's Actions cache:apt-get updateand no download.apt-get update, then downloads only what the restored archives lack, installs, keeps only the archives this host needed, and saves under the new key.apt-get update, download, install. Then it saves.The key is
latex-apt-<os>-<arch>-<cache-version>-<hash of the list>-<hash of the installed packages>. The archives a run downloads are exactly the packages its host lacked, so a host with the same packages installed needs exactly those, and an exact hit is complete.What changed from the agreed design
An exact hit installs with the cache directory as apt's archive directory. The check proposed installing the cached archives as local
./*.debfiles with downloads disabled. On a runner, both halves failed:--no-downloadmakes apt refuse the local files too.With
-o Dir::Cache::archives=<the cache>, apt finds each archive there and fetches nothing, and a version only the file carries is read in place. The completeness check isapt-get install --print-uris, which lists what apt would fetch. On the image's own stale lists, with every mirror refused, it listed nothing, and the install needed 0 B.Nothing else. The inputs, the output, the defaults, the key, the save rule and the timeout are as decided on Cache the TeX Live apt install: a slow Ubuntu mirror stalls PDF builds for hours #224.
Changes
setup-latex/action.yml(new)packagesandrequirements-file(exactly one),cache-version(defaultv1; letters, digits,.and_, so that no version's key starts with another's) anddownload-timeout-minutes(default30,'0'for no limit); outputcache-hit, meaning whatconda-cache-hitmeans. Steps, in order: check inputs (single_lineon the three one-value inputs, then the list); container detection; prepare;actions/cache/restore@v6; install;actions/cache/save@v6when the install says so. The save runs right after the install, so a later step's failure still keeps the download.scripts/latex-packages.sh(new)setup-environmentcan use it in the second PR.listparses the list assetup-environmentdoes today (whitespace or newlines,#comments, CRLF), refuses any entry that is not an apt package name (which also keeps a token from starting with-or::), and writes it sorted.preparecomputes the key and makes the cache directory,/var/cache/quantecon-actions/latex-apt, owned by the runner user and outside$HOME, so that apt's_aptuser can read it.installis the hit path, the fallback path and the miss path, and decides the save: not after an exact hit, not when nothing was needed, and not from a tag ref, whose cache no later run could restore.docs/user/actions/setup-latex.md(new)apt-getstep, with the before and after; the cache key and why it hashes the installed packages; where caches are shared, including what a repository that builds the PDF only on pull requests and tags gets; versions and trust; when to lower, raise or turn off the timeout, from the measured slow runs; and troubleshooting for each message.setup-latex/README.md,docs/user/README.md,scripts/generate-docs.pysetup-latexaftersetup-environmentinORDER..github/workflows/test-actions.ymlsetup-environmentones, all inharness-summary'sneeds::latex-seed,latex-hit,latex-fallback,latex-timeoutandlatex-inputs. And asetup-latexcase ininputs-line-break. See below..github/fixtures/setup-latex/(new)apt-proxy.py, a stand-in for apt's proxy that either refuses and records every request, or trickles one byte every 2 s forever with noContent-Length. Andcheck-tex.sh: packages installed and configured, andpdflatexcompiles a page, which needs the formatfmtutilbuilds from dpkg's trigger.docs/dev/TESTING.mdsetup-latexrow.docs/dev/ARCHITECTURE.mdsetup-latexin the list, and the shared scripts row names the cached LaTeX install.docs/user/security.mdsetup-latex'spackagesjoins the inputs that may span lines.templates/latex-requirements.txtsetup-latex, and its format note now matches the parser. It said a comment must start its line;#starts one anywhere.CHANGELOG.md[Unreleased],### Added, above #280's### Changed. NoThe harness jobs
latex-seedcache-hitempty,texlive-latex-baseinstalled and configured, apdflatexpage compiled, and the cache saved, found again byactions/cache/restorewithlookup-only.latex-hitapt-get updatesends it 24 requests, then clears the log. After the action:cache-hit == 'true', no request recorded, the package configured, andpdflatexworking. On a different image, as during a rollout, it checks the fallback install instead, with a notice, rather than flake.latex-fallbackdvipng:cache-hit == 'false', both packages work, every archive kept for the cache is installed at its version, and dvipng's is among them.latex-timeoutdownload-timeout-minutes: '1'the action fails, between 55 and 150 s in, after apt made requests through the stand-in, and with noapt-getleft running.latex-inputs-incache-version. Then, on a runner marked as a container-mode host, a working call installs nothing, and a call with no list still fails.inputs-line-breakrequirements-filefails the first step, before the list is read.What I checked, and how
The issue check. It is on #224, agreed with the maintainer through the organiser, with their five decisions. In short:
setup-environmentcannot reach a new action throughuses:, since@v0runs the released copy and./resolves against the caller's workspace, so the two share a script;Acquire::Retries "1"on purpose, so the issue's-o Acquire::Retries=3was dropped;timeout-minutes, so the limit is atimeoutaroundupdateand the download, never dpkg;ImageOS/ImageVersion.On real runners, before opening this PR. I ran the five jobs from throwaway branches (each deleted afterwards), and three one-job probes of apt's behaviour. They changed the design in two places:
--no-downloadcannot be used. apt refuses even local.debfiles with it ("Unable to fetch some archives"), so the first completeness check always failed, and every hit went online.Dir::Cache::archives, it finds each archive there and fetches nothing. A probe on the image's own stale lists, with every mirror refused, showed--print-urislisting nothing, "Need to get 0 B/105 MB", zero requests, and workingpdflatex,dvipngandgs. So--print-urisis the completeness check, and the install reads the cache directory.The timeout's stand-in also needed two attempts. apt fails at once a 1 GB
Content-Length, which is past its 10 MB InRelease limit, and a response with no length too. It now says 5 MB, and never finishes.Measured in the passing run of the five jobs, with
texlive-latex-base(34 packages, 105 MB):dvipngThe exact key matched on the second VM, so the installed-packages hash is the same on two runners of one image.
The new hit test fails on today's code. A throwaway branch from
mainranlatex-hit's stand-in and assertions againstmain'ssetup-environmentwithinstall-latex: 'true'(run 42349915064).apt-get updatewent through the stand-in, and the install failed with exit 100 on "Failed to fetch". The assertion then failed: "the install made 160 requests through apt (above): it ran apt-get update or downloaded".The local checks, with actionlint 1.7.12 (its release's SHA-256 checked) and shellcheck 0.11.0. These are clean:
python3 scripts/generate-docs.py --check --check-examples --actionlint …,actionlint,python3 scripts/lint-shell.py, and shellcheck oncheck-tex.sh.git diff origin/main...HEAD --numstat -- CHANGELOG.mdshows 16 additions and no deletions, and everything from## [0.16.0]down is unchanged.What to watch after merge
Nothing runs at merge, since nothing calls the action. It ships in v0.17.0.
At the staged release, the canary should exercise it. The canary builds only in a container, so its own workflows skip it. On the staging pull request, add a throwaway workflow with two standard-runner jobs, a miss and then a hit, each running
setup-latex@vX.Y.Zwith the canary's ownlatex-requirements.txt(the real list, about 1.1 GB), thenpdflatexon one page. Check that the second job's log showscache-hit: true, noapt-get updategroup and noGet:line, and that the first job's log ends with "Cache saved".When a lecture repository adopts it, its first run downloads as today and saves about 1.1 GB, or 1.4 GB with
latex-cjk-all. Later runs on the same runner image install from the cache.Not in this PR
setup-environment'sinstall-latexon the same script and cache: the second PR, which waits for Monday's lecture-matrix run.setup-latex: the maintainer's rollout, after v0.17.0.Part of #224.
🤖 Generated with Claude Code
https://claude.ai/code/session_01WT8bMXtFLfZrVgBA6ycXev