https://github.com/step-security/setup-zig
Install a Zig compiler for usage in GitHub Actions workflows. Secure drop-in replacement for mlugg/setup-zig.
https://github.com/step-security/setup-zig
step-security-maintained-actions
Last synced: 4 months ago
JSON representation
Install a Zig compiler for usage in GitHub Actions workflows. Secure drop-in replacement for mlugg/setup-zig.
- Host: GitHub
- URL: https://github.com/step-security/setup-zig
- Owner: step-security
- License: mit
- Created: 2024-11-25T18:07:45.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-01-26T00:08:58.000Z (5 months ago)
- Last Synced: 2026-01-26T15:28:18.791Z (5 months ago)
- Topics: step-security-maintained-actions
- Language: JavaScript
- Homepage: https://docs.stepsecurity.io/actions/stepsecurity-maintained-actions
- Size: 19.8 MB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# setup-zig
Install the Zig compiler for use in an Actions workflow, and preserve the Zig cache across workflow runs.
## Usage
```yaml
jobs:
test:
runs-on: ubuntu-latest
name: Build and Test
steps:
- uses: actions/checkout@v3
- uses: step-security/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][mach-nominated], 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.
```yaml
- uses: step-security/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:
```yaml
- uses: step-security/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][report-bad-mirror] on the Zig
website repository, which is where the list of mirrors is maintained.
If necessary, the caching of the global and local Zig cache directories 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][matrix] 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`.
[mach-nominated]: https://machengine.org/about/nominated-zig/
[matrix]: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow
[report-bad-mirror]: https://github.com/ziglang/www.ziglang.org/issues/new
## 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][mirrors] from
ziglang.org is used. If you are interested in hosting a mirror of your own, check out the
[documentation][host-mirror] 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!
[mirrors]: https://ziglang.org/download/community-mirrors/
[host-mirror]: https://github.com/ziglang/www.ziglang.org/blob/main/MIRRORS.md