setup-zig

Install the Zig compiler for use in an Actions workflow, and preserve the Zig cache across workflow runs.

Usage

jobs:
  test:
    runs-on: ubuntu-latest
    name: Build and Test
    steps:
      - uses: actions/checkout@v3
      - uses: mlugg/setup-zig@v2
      - run: zig build test

This will automatically download Zig and install it to PATH.

You can use version to set a Zig version to download. This may be a release (0.13.0), a specific nightly build (0.14.0-dev.2+0884a4341), the string master for the latest nightly build, or the string latest for the latest full release. It can also refer to a Mach nominated version, such as 2024.5.0-mach. Finally, leaving the value empty (the default) will cause the action to attempt to resolve the Zig version from the minimum_zig_version field in build.zig.zon, falling back to latest if that isn't possible.

  - uses: mlugg/setup-zig@v2
    with:
      version: 0.13.0

Warning

Mirrors, including the official Zig website, may purge old nightly builds at their leisure. This means that if you target an out-of-date nightly build, such as a 0.11.0-dev build, the download may fail.

If you want to use one specific mirror, you can set it using the mirror option:

  - uses: mlugg/setup-zig@v2
    with:
      mirror: 'https://pkg.machengine.org/zig'

Please don't do this unnecessarily; it's not nice to hammer one mirror. This mirror is not permitted to be https://ziglang.org/download to avoid the official website being hit with large amounts of requests. If you've experienced issues with a default mirror, please open an issue on the Zig website repository, which is where the list of mirrors is maintained.

If necessary, the caching of the global Zig cache directory can be disabled by setting the option use-cache: false. Don't do this without reason: preserving the Zig cache will typically speed things up and decrease the load on GitHub's runners.

If you are using a matrix strategy for your workflow, you may need to populate the cache-key option with all of your matrix variables to ensure that every job is correctly cached. Unfortunately, GitHub does not provide any means for the Action to automatically distinguish jobs in a matrix. However, variables which select the runner OS can be omitted from the cache-key, since the runner OS is included in the cache key by default.

Zig cache directories can get incredibly large over time. By default, this Action will clear the cache directory once its size exceeds 2 GiB. This threshold can be changed by setting the cache-size-limit option to a different value (in MiB); for instance, cache-size-limit: 4096 for a 4 GiB limit. The limit can be disabled entirely by setting cache-size-limit: 0.

Details

This action attempts to download the requested Zig tarball from a set of mirrors, in a random order. As a last resort, the official Zig website is used. The tarball's minisign signature is also downloaded and verified to ensure binaries have not been tampered with. The tarball is cached between runs and workflows.

The global Zig cache directory (~/.cache/zig on Linux) is automatically cached between runs, and all local caches are redirected to the global cache directory to make optimal use of this cross-run caching.

Adding a mirror

The list of tarball mirrors is not in this repository; rather, the community mirror list from ziglang.org is used. If you are interested in hosting a mirror of your own, check out the documentation on the Zig website repository. That way, your mirror can benefit not just setup-zig, but also any other tooling which wants to fetch Zig!