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.

With Node.js v16 having reached its end-of-life and GitHub Actions beginning the transition to Node.js v20, the action has upgraded its default runtime to Node.js v20.

If you are using a self-hosted runner, please update it to v2.308.0 or later to ensure node20 runtime functionality.

To be more consistent with official actions such as actions/cache, the cache-hit output is now set to true only if a cache is found that exactly matches the specified version and package set. To simply check if a cache was found, use cache-restored instead:

- uses: teatimeguest/setup-texlive-action@v3
  id: setup

- if: fromJSON(steps.setup.outputs.cache-restored)
  run: echo 'A cache has been found'

Actions published on GitHub Marketplace have unique names defined in the metadata file action.yml. To minimize conflicts with other actions, the action name (setup-texlive-action) is now used for the following things:

• Directory name of the default installation prefix:

  - $RUNNER_TEMP/setup-texlive
  + $RUNNER_TEMP/setup-texlive-action
  

• Environment variable name:

  - SETUP_TEXLIVE_FORCE_UPDATE_CACHE
  + SETUP_TEXLIVE_ACTION_FORCE_UPDATE_CACHE
  

• Cache keys.

As with install-tl's portable installation, user directories are now set by default to be the same as the corresponding system directories. To emulate the previous behavior, specify the user directories explicitly using environment variables:

- uses: teatimeguest/setup-texlive-action@v3
  env:
    TEXLIVE_INSTALL_TEXMFHOME: ~/texmf
    TEXLIVE_INSTALL_TEXMFCONFIG: ~/.local/texlive/<version>/texmf-config
    TEXLIVE_INSTALL_TEXMFVAR: ~/.local/texlive/<version>/texmf-var

The package-file input now accepts glob patterns to specify multiple files:

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

This change might break existing workflow behavior since special characters such as * and ? will need to be escaped.

Table of Contents

• Usage
  ⎿
  
  Basic Usage
  ・
  Caching
  ・
  Historic Versions
  
• Inputs
• Outputs
• Environment Variables
• Permissions
• Troubleshooting
  ⎿
  
  Dependency Issues
  ・
  Repository-Related Issues
  ・
  Local Testing
  ・
  Debug Logging
  
• 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.

2008–2024

2013–2024

📝 Versions prior to 2013 are for 32-bit systems and will not work due to Bad CPU type in executable.

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, but excluding 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

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:

• TeXFindPkg — Query or install TeX packages and their dependencies
• DEPP — Dependency Printer for TeX Live
• 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, a repository has problems with, for example, SSL certificates or package checksums, 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:

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. Please refer to the official documentation for the repository URL format.

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:

--platform ubuntu-latest=node:20
--pull=false
--detect-event
--env RUNNER_DEBUG=1           # Enable debug logging
# --env NODE_DEBUG=<module>    # Might be useful in few cases

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.