minted package fails in CI when restricted shell-escape omits pygmentize

Resolution

Use minted with the frozen option and an explicit cachedir, then generate the .pyg cache files in a CI preparation step that runs pygmentize directly from the shell rather than through TeX's shell-escape mechanism. Pinning the Pygments version makes the output reproducible, and the frozen cache lets the actual LaTeX compile run without --shell-escape.

Likely Explanation vs. Confirmed Facts

Likely explanation: The restricted shell_escape_commands whitelist omits pygmentize, so minted cannot invoke it at runtime and aborts with the -shell-escape error. Confirmed facts: minted calls pygmentize via the shell unless a frozen cache is present; the CI policy forbids full shell-escape; and the whitelist is fixed by the distribution image.

Recommended Workflow

1. Pin the Pygments version in CI, for example with a fixed Docker image or a pinned pip requirement.
2. Before the LaTeX job, run a script that invokes pygmentize for every code block and writes the results into the cache directory that minted expects.
3. Load the package with \usepackage[cachedir=minted-cache,frozen]{minted}. Add outputdir=build only if you compile with -output-directory.
4. Run latexmk or pdflatex without --shell-escape. The frozen cache satisfies minted without any external calls.

If pre-generating the cache inside the restricted runner is impractical, the fallback is to generate the cache once in a trusted environment with the same pinned Pygments version and publish it as a build artifact, but do not commit the _minted-* directory to source control.

Does pythontex avoid the whitelist?

Yes. In its normal two-pass workflow, pythontex is executed as a standalone script between LaTeX runs. Because the script is launched directly by the CI shell rather than by TeX's restricted shell-escape subsystem, the shell_escape_commands whitelist does not apply. pythontex also does not use pygmentize; it runs Python directly. The trade-off is that you must rewrite code blocks with pythontex commands instead of minted environments.

TeX Live version note

repstopdf has been present in the default restricted whitelist for many years, whereas pygmentize has never been included by default. The exact minimal TeX Live version is distribution-specific; verify it in your image rather than assuming a cutoff.

kpsewhich -var-value shell_escape_commands

Verification

After generating the cache, run the compile with -interaction=nonstopmode and confirm that no pygmentize process is spawned. A practical check is to compare the PDF checksum between a local full-shell-escape build and the CI frozen build; they should match when the Pygments version and style are identical.