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@v1
      - 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. The default is latest.

  - uses: mlugg/setup-zig@v1
    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@v1
    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, and I will communicate with the mirror's owner or remove it from the list.

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.

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

Anyone is welcome to host a Zig download mirror; thanks to the tarball signatures, the mirror provider need not be trusted. Naturally, if a mirror is found to be a bad actor, it will be removed, and likewise if a mirror repeatedly encounters reliability problems.

The rules for adding a mirror are listed below. Note that I (@mlugg) reserve the right to, for any or no reason, exclude mirrors which obey these rules, or include mirrors which violate them.

Note

While there are a lot of rules listed here, most of them should be obvious. They are stated explicitly here to ensure complete clarity on what is expected of a mirror. Please do read these requirements through before attempting to add a mirror.

• A mirror provides a single base URL, which we will call X.
• X may include a path component, but is not required to. For instance, https://foo.bar/zig/ is okay, as is https://zig.baz.qux/.
• The mirror must have working HTTPS support. X must start with https://.
• The mirror must cache tarballs locally. For instance, it may not simply forward all requests to another mirror.
• The mirror may routinely evict its local tarball caches based on any reasonable factor, such as age, access frequency, or the existence of newer versions. This does not affect whether the mirror may return 404 for requests to these files (see below).
• The mirror must download its tarballs from either https://ziglang.org/, or another mirror which follows these rules.
• Tarballs must be accessible by sending GET requests for files under X, where the filename matches that of the files provided by https://ziglang.org/, not including the directory part. For instance, X/zig-linux-x86_64-0.13.0.tar.xz is a valid access, and should return the same file as https://ziglang.org/download/0.13.0/zig-linux-x86_64-0.13.0.tar.xz.
• Files provided by the mirror must be bit-for-bit identical to their https://ziglang.org/ counterparts.
• If a file is accessed whose Zig version is a master branch build (i.e. a -dev version), and the version is ordered before the latest major release of Zig, the mirror may respond with 404 Not Found, but is not required to. For instance, at the time of writing, 0.13.0 is the latest major release of Zig, so a mirror may respond with 404 for 0.13.0-dev... builds, but not for 0.14.0-dev... builds.
• If a file is accessed whose Zig version is 0.5.0 or below, the mirror may respond with 404 Not Found, but is not required to.
• If a file is acccessed which represents a source tarball, such as X/zig-0.13.0.tar.xz, the mirror may respond with 404 Not Found, but is not required to. The same applies to "bootstrap source tarballs", such as X/zig-bootstrap-0.13.0.tar.xz.
• For all other accesses of valid Zig tarballs, the mirror must respond with status code 200 OK and the file in question. If the mirror has not yet cached the file locally, it should immediately download it from a permitted source (as covered above), and respond with the downloaded file.
• If a tarball X/foo.ext is available by the above rules, requesting the minisign signature file X/foo.ext.minisig must also respond with status code 200 OK and the signature file in question, like the tarball itself.
• The mirror may rate-limit accesses. If an access failed due to rate-limiting, the mirror should return HTTP status code 429 Too Many Requests.
• The mirror may undergo maintenance, upgrades, and other scheduled downtime. If an access fails for this reason, where possible, the mirror should return HTTP status code 503 Unavailable. The mirror should try to minimize such downtime.
• The mirror may undergo occasional unintended and unscheduled downtime. The mirror must go to all efforts to minimize such outages, and must resolve such outages within a reasonable time upon being notified of them.
• The mirror may observe the ?source=github-actions query parameter to track how many requests originate from this Action. This Action will provide this query parameter to all mirror requests.

The easiest way to set up a mirror right now is using Mach's Wrench. For instructions, please see the relevant section of their README.

After setting up a mirror, you can add it to this GitHub Action by opening a PR which adds it to the list in mirrors.json.