setup-texlive-action

A GitHub Action to set up TeX Live

This action provides the following functionality:

• Installing and setting up a specific version of TeX Live;
• Caching and restoring TEXDIR by default to improve workflow execution time;
• Optionally configuring an additional package repository and installing TeX packages.

Linux, Windows, and macOS are supported.

Breaking Changes in V3

In most cases, you can upgrade from v2 to v3 without changing your workflow.

Table of Contents

• Usage
  • Basic Usage
  • Caching
  • Historic Versions
• Inputs
• Outputs
• Environment Variables
• Permissions
• Troubleshooting
• Changelog
• License

Usage

Basic Usage

- name: Setup TeX Live
  uses: teatimeguest/setup-texlive-action@v3
  with:
    packages: scheme-basic

To make it suitable for CI use, by default, the action will only set up tlmgr (TeX Live package manager) and will not install any TeX packages, even basic commands such as pdflatex. If you want to install some TeX packages, you can use the packages input:

- uses: teatimeguest/setup-texlive-action@v3
  with:
    packages: |
      scheme-basic
      hyperref
      microtype

  # `pdflatex` is now available
  # along with hyperlink and microtypography support.

[!NOTE]\ Since tlmgr does not manage package dependencies, you will need to explicitly specify all the packages you depend on. If you are not sure exactly which packages are required, it is recommended to install at least scheme-basic, which contains the most basic packages such as latex and amsmath.

See also "Troubleshooting."

You can also specify packages by file using the package-file input:

- uses: actions/checkout@v4
- uses: teatimeguest/setup-texlive-action@v3
  with:
    package-file: |
      .github/tl_packages
      **/DEPENDS.txt

Caching

By default, the action will save TEXDIR to cache using @actions/cache. This is done in the post-process of a completed workflow job, so that, for example, LuaTeX font cache files generated in your job are also saved and restored as part of the cache entry.

If you have problems due to a corrupt cache entry, you can delete it from the web interface, GitHub CLI, or REST API. For an example of programmatically deleting cache entries created by this action using actions/github-script, see this script.

If you want to disable caching, set the cache input to false:

- uses: teatimeguest/setup-texlive-action@v3
  with:
    cache: false

Historic Versions

You can use an older version of TeX Live by setting the version input:

- uses: teatimeguest/setup-texlive-action@v3
  with:
    version: 2008

The action will install an older version using historic archive with small patches to fix minor problems.

Inputs

All inputs are optional.

Outputs

Environment Variables

The action reads the following environment variable:

In addition, the official environment variables for install-tl are supported, with the exception of TEXLIVE_INSTALL_TEXMFSYS(CONFIG|VAR) in order to ensure system directories are cached correctly.

To specify the installation prefix, either the input prefix or the environment variable TEXLIVE_INSTALL_PREFIX can be used, with prefix taking precedence if both are set. Precedence for all other texmf-related inputs and environment variables follows the behavior of the latest version of install-tl.

Permissions

This action does not use GITHUB_TOKEN and does not require any permissions.

Troubleshooting

If a problem persists, feel free to open an issue.

• Dependency Issues
• Repository-Related Issues
• Local Testing
• Debug Logging

Dependency Issues

Unlike other package managers such as pip or npm, TeX Live (tlmgr) has very little dependency management, so generally it is difficult to determine exactly which packages you need. Lacking some indirect dependencies, you may often encounter compilation errors like:

! LaTeX Error: File `XXXXX.sty` not found.

While there is no perfect solution, there are some tools that can help address this problem:

Name	Version	Description
DEPP		Dependency Printer for TeX Live
TeXFindPkg		Query or install TeX packages and their dependencies
texliveonfly		On-the-fly download of missing TeX live packages

Repository-Related Issues

By default, the action automatically picks one of the CTAN mirrors and sets it as the main package repository for the installation. Infrequently, there may be some problem with the repository, causing setup to fail with log messages like:

• Error: unable to verify the first certificate

• TeXLive::TLUtils::check_file_and_remove:
  checksums differ for /tmp/path/to/some/package.tar.xz:

• gpg: BAD signature from "TeX Live Distribution <tex-live@tug.org>" [ultimate]

In most cases, these problems do not last so long and after a while the workflow should be stable again.

Alternatively, you can pin the main repository using the repository input to avoid using problematic repositories:

- uses: teatimeguest/setup-texlive-action@v3
  with:
    repository: https://example.com/path/to/systems/texlive/tlnet/

For more information on the repository URL format, see "3.3.1 The -repository option" in the official TeX Live documentation.

Local Testing

If you are using a container engine such as docker, act allows you to run a workflow locally inside a container environment, without having to push changes to GitHub, saving a lot of time in setup for CI. This action can be run on a node:20 image, so the following configuration is a good starting point for testing or debugging with act:

Debug Logging

On GitHub, debug logging can be enabled without modifying a workflow file by setting repository configuration variables. See the GitHub Docs for more information.

Changelog

See the releases page.

License

MIT License

For third-party software licenses and copyright notices, please refer to dist/NOTICE.md.