determinate-nix-action/README.md

140 lines
13 KiB
Markdown
Raw Normal View History

2025-05-15 15:54:26 +01:00
<p align="center">
<a href="https://determinate.systems" target="_blank"><img src="https://raw.githubusercontent.com/determinatesystems/.github/main/.github/banner.jpg"></a>
</p>
<p align="center">
&nbsp;<a href="https://determinate.systems/discord" target="_blank"><img alt="Discord" src="https://img.shields.io/discord/1116012109709463613?style=for-the-badge&logo=discord&logoColor=%23ffffff&label=Discord&labelColor=%234253e8&color=%23e4e2e2"></a>&nbsp;
&nbsp;<a href="https://bsky.app/profile/determinate.systems" target="_blank"><img alt="Bluesky" src="https://img.shields.io/badge/Bluesky-0772D8?style=for-the-badge&logo=bluesky&logoColor=%23ffffff"></a>&nbsp;
&nbsp;<a href="https://hachyderm.io/@determinatesystems" target="_blank"><img alt="Mastodon" src="https://img.shields.io/badge/Mastodon-6468fa?style=for-the-badge&logo=mastodon&logoColor=%23ffffff"></a>&nbsp;
&nbsp;<a href="https://twitter.com/DeterminateSys" target="_blank"><img alt="Twitter" src="https://img.shields.io/badge/Twitter-303030?style=for-the-badge&logo=x&logoColor=%23ffffff"></a>&nbsp;
&nbsp;<a href="https://www.linkedin.com/company/determinate-systems" target="_blank"><img alt="LinkedIn" src="https://img.shields.io/badge/LinkedIn-1667be?style=for-the-badge&logo=linkedin&logoColor=%23ffffff"></a>&nbsp;
</p>
# ️❄️ Determinate Nix Action
2025-05-14 17:20:48 -04:00
2025-05-16 12:39:52 -04:00
[Determinate] is the best way to use Nix on macOS, WSL, and Linux.
2025-05-14 17:20:48 -04:00
It is an end-to-end toolchain for using Nix, from installation to collaboration to deployment.
2025-05-16 12:39:52 -04:00
Based on the [Determinate Nix Installer][nix-installer] and its corresponding [Nix Installer Action][nix-installer-action], responsible for over tens of thousands of Nix installs daily.
2025-05-14 17:20:48 -04:00
> [!NOTE]
>
2025-05-16 12:39:52 -04:00
> **Why a different Action?**
>
2025-05-16 12:39:52 -04:00
> We created a new Action to synchronize version tags to [Determinate Nix][det-nix] releases.
> GitHub Actions are tagged with the specific version, like `v3.5.2`, with a moving `v3` tag for the major version.
2025-05-16 12:39:52 -04:00
> We needed a fresh tag namespace since `nix-installer-action` already has a `v3` tag.
2025-05-15 15:54:26 +01:00
## 🫶 Platform support
2025-05-14 17:20:48 -04:00
2025-05-15 15:54:26 +01:00
-**Accelerated KVM** on open source projects and larger runners. See [GitHub's announcement](https://github.blog/changelog/2023-02-23-hardware-accelerated-android-virtualization-on-actions-windows-and-linux-larger-hosted-runners/) for more info.
- 🐧 Linux, x86_64, aarch64, and i686
- 🍏 macOS, x86_64 and aarch64
- 🪟 WSL2, x86_64 and aarch64
- 🐋 Containers, ARC, and Act
- 🐙 GitHub Enterprise Server
- 💁 GitHub Hosted, self-hosted, and long running Actions Runners
2025-05-14 17:20:48 -04:00
2025-05-15 15:54:26 +01:00
## ️🔧 Usage
2025-05-14 17:20:48 -04:00
2025-05-15 15:09:41 -04:00
Here's an example Actions workflow configuration that uses `determinate-nix-action`:
2025-05-14 17:20:48 -04:00
```yaml
on:
pull_request:
push:
branches: [main]
jobs:
2025-05-15 15:09:41 -04:00
build-pkg:
name: Build Nix package
2025-05-14 17:20:48 -04:00
runs-on: ubuntu-latest
permissions:
2025-05-15 15:09:41 -04:00
id-token: write
contents: read
2025-05-14 17:20:48 -04:00
steps:
- uses: actions/checkout@v5.0.0
- uses: DeterminateSystems/determinate-nix-action@main # or v3.13.1 to pin to a release
2025-05-14 17:20:48 -04:00
- run: nix build .
```
2025-05-15 15:09:41 -04:00
> [!IMPORTANT]
2025-05-15 16:03:22 -04:00
> If you use [FlakeHub], you need to add a `permissions` block like the one in the example above or else Determinate Nix can't authenticate with FlakeHub or [FlakeHub Cache][cache].
2025-05-15 15:09:41 -04:00
2025-05-16 12:39:52 -04:00
## 📌 Version pinning: lock it down!
2025-05-14 17:20:48 -04:00
2025-05-16 12:39:52 -04:00
### Why pin your Action?
2025-05-14 17:20:48 -04:00
2025-05-15 15:54:26 +01:00
Unlike `DeterminateSystems/nix-installer-action`, we fully support explicit version pinning for maximum consistency.
2025-05-16 12:39:52 -04:00
This Action is **automatically tagged** for every Determinate Nix release, giving you complete control over your CI environment:
2025-05-14 17:20:48 -04:00
📍 Pinning to `DeterminateSystems/determinate-nix-action@v3.13.1` guarantees:
- Same `nix-installer-action` revision every time
- Consistent Determinate Nix v3.13.1 installation
- Reproducible CI workflows, even years later
2025-05-15 15:54:26 +01:00
✨ Using `@main` instead? You'll:
2025-05-14 17:20:48 -04:00
- Always get the latest Determinate Nix release
- Occasionally participate in phased rollouts (helping us test new releases!)
> [!IMPORTANT]
2025-05-16 12:39:52 -04:00
> Set up [Dependabot] to stay current with Determinate Nix releases without sacrificing stability.
2025-05-14 17:20:48 -04:00
2025-05-16 12:39:52 -04:00
### 🤖 Automate updates with Dependabot
2025-05-14 17:20:48 -04:00
2025-05-16 12:39:52 -04:00
Keep your GitHub Actions fresh without manual work! Create `.github/dependabot.yml` with:
2025-05-14 17:20:48 -04:00
```yaml
version: 2
updates:
2025-05-16 12:39:52 -04:00
- package-ecosystem: github-actions
directory: /
2025-05-14 17:20:48 -04:00
schedule:
2025-05-16 12:39:52 -04:00
interval: weekly
2025-05-14 17:20:48 -04:00
```
2025-05-15 15:54:26 +01:00
## ️⚙️ Configuration
2025-05-14 17:20:48 -04:00
| Parameter | Description | Required | Default |
|-------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----------------------------|
| `extra-conf` | Extra configuration lines for `/etc/nix/nix.conf` (includes `access-tokens` with `secrets.GITHUB_TOKEN` automatically if `github-token` is set) | | |
| `github-server-url` | The URL for the GitHub server, to use with the `github-token` token. Defaults to the current GitHub server, supporting GitHub Enterprise Server automatically. Only change this value if the provided `github-token` is for a different GitHub server than the current server. | | `${{ github.server_url }}` |
| `github-token` | A GitHub token for making authenticated requests (which have a higher rate-limit quota than unauthenticated requests) | | `${{ github.token }}` |
2025-05-15 16:32:20 -04:00
| `trust-runner-user` | Whether to make the runner user trusted by the Nix daemon | | `true` |
| `force-no-systemd` | Force using other methods than systemd to launch the daemon. This setting is automatically enabled when necessary. | | `false` |
2025-05-14 17:20:48 -04:00
| `init` | The init system to configure, requires `planner: linux-multi` (allowing the choice between `none` or `systemd`) | | |
2025-05-15 16:32:20 -04:00
| `kvm` | Automatically configure the GitHub Actions Runner for NixOS test supports, if the host supports it. | | `true` |
2025-05-14 17:20:48 -04:00
| `planner` | A planner to use | | |
| `proxy` | The proxy to use (if any), valid proxy bases are `https://$URL`, `http://$URL` and `socks5://$URL` | | |
2025-05-15 16:32:20 -04:00
| `reinstall` | Force a reinstall if an existing installation is detected (consider backing up `/nix/store`) | | `false` |
2025-05-14 17:20:48 -04:00
| `source-binary` | Run a version of the nix-installer binary from somewhere already on disk. Conflicts with all other `source-*` options. Intended only for testing this Action. | | |
| `source-branch` | The branch of `nix-installer` to use (conflicts with `source-tag`, `source-revision`, `source-pr`) | | |
| `source-pr` | The PR of `nix-installer` to use (conflicts with `source-tag`, `source-revision`, `source-branch`) | | |
| `source-revision` | The revision of `nix-installer` to use (conflicts with `source-tag`, `source-branch`, `source-pr`) | | |
| `source-tag` | The tag of `nix-installer` to use (conflicts with `source-revision`, `source-branch`, `source-pr`) | | `v3.13.1` |
2025-05-14 17:20:48 -04:00
| `source-url` | A URL pointing to a `nix-installer` executable | | |
| `backtrace` | The setting for `RUST_BACKTRACE` (see https://doc.rust-lang.org/std/backtrace/index.html#environment-variables) | | |
| `diagnostic-endpoint` | Diagnostic endpoint url where the installer sends data to. To disable set this to an empty string. | | `-` |
| `log-directives` | A list of Tracing directives, comma separated, `-`s replaced with `_` (eg. `nix_installer=trace`, see https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives) | | |
| `logger` | The logger to use for install (eg. `pretty`, `json`, `full`, `compact`) | | |
2025-05-15 16:32:20 -04:00
| `_internal-strict-mode` | Whether to fail when any errors are thrown. Used only to test the Action; do not set this in your own workflows. | | `false` |
2025-05-14 17:20:48 -04:00
2025-05-16 12:39:52 -04:00
## 🛟 Need help? We're here for you!
2025-05-15 15:54:26 +01:00
We're committed to making your experience with Determinate Nix as smooth as possible. If you encounter any issues or have questions, here's how to reach us:
2025-05-14 17:20:48 -04:00
2025-05-15 15:54:26 +01:00
- 🐛 **Found a bug?** [Open an issue](https://github.com/DeterminateSystems/determinate-nix-action/issues/new) on GitHub
- 💬 **Want to chat?** Join our [Discord community](https://determinate.systems/discord) for quick help and discussions
- 📧 **Need direct support?** Email us at [support@determinate.systems](mailto:support@determinate.systems)
2025-05-14 17:20:48 -04:00
🤝 **Looking for enterprise support?** We offer dedicated support contracts and shared Slack channels for organizations requiring priority assistance. [Contact us](mailto:support@determinate.systems) to learn more.
2025-05-15 15:09:41 -04:00
2025-05-15 16:03:22 -04:00
[cache]: https://flakehub.com/cache
2025-05-16 12:39:52 -04:00
[dependabot]: https://github.com/dependabot
[det-nix]: https://docs.determinate.systems/determinate-nix
[determinate]: https://docs.determinate.systems
2025-05-15 15:09:41 -04:00
[flakehub]: https//flakehub.com
2025-05-16 12:39:52 -04:00
[nix-installer]: https://github.com/DeterminateSystems/nix-installer
[nix-installer-action]: https://github.com/DeterminateSystems/nix-installer-action