mirror of
https://github.com/DeterminateSystems/flake-checker.git
synced 2024-10-27 07:34:24 +03:00
112 lines
5.3 KiB
Markdown
112 lines
5.3 KiB
Markdown
# Nix Flake Checker
|
|
|
|
[](https://flakehub.com/flake/DeterminateSystems/flake-checker)
|
|
|
|
**Nix Flake Checker** is a tool from [Determinate Systems][detsys] that performs "health" checks on the [`flake.lock`][lockfile] files in your [flake][flakes]-powered Nix projects.
|
|
Its goal is to help your Nix projects stay on recent and supported versions of [Nixpkgs].
|
|
|
|
To run the checker in the root of a Nix project:
|
|
|
|
```shell
|
|
nix run github:DeterminateSystems/flake-checker
|
|
|
|
# Or point to an explicit path for flake.lock
|
|
nix run github:DeterminateSystems/flake-checker /path/to/flake.lock
|
|
```
|
|
|
|
Nix Flake Checker looks at your `flake.lock`'s root-level [Nixpkgs] inputs and checks that:
|
|
|
|
- Any explicit Nixpkgs Git refs are in this list:
|
|
- `nixos-23.05`
|
|
- `nixos-23.05-small`
|
|
- `nixos-unstable`
|
|
- `nixos-unstable-small`
|
|
- `nixpkgs-23.05-darwin`
|
|
- `nixpkgs-unstable`
|
|
- Any Nixpkgs dependencies are less than 30 days old
|
|
- Any Nixpkgs dependencies have the [`NixOS`][nixos-org] org as the GitHub owner (and thus that the dependency isn't a fork or non-upstream variant)
|
|
|
|
If you're running it locally, Nix Flake Checker reports any issues via text output in your terminal.
|
|
But you can also use Nix Flake Checker [in CI](#the-flake-checker-action).
|
|
|
|
## The Nix Flake Checker Action
|
|
|
|
You can automate Nix Flake Checker by adding Determinate Systems' [Nix Flake Checker Action][action] to your GitHub Actions workflows:
|
|
|
|
```yaml
|
|
checks:
|
|
steps:
|
|
- uses: actions/checkout@v3
|
|
- name: Check Nix flake Nixpkgs inputs
|
|
uses: DeterminateSystems/flake-checker-action@main
|
|
```
|
|
|
|
When run in GitHub Actions, Nix Flake Checker always exits with a status code of 0 by default—and thus never fails your workflows—and reports its findings as a [Markdown summary][md].
|
|
|
|
## Telemetry
|
|
|
|
The goal of Nix Flake Checker is to help teams stay on recent and supported versions of Nixpkgs.
|
|
The flake checker collects a little bit of telemetry information to help us make that true.
|
|
|
|
Here is a table of the [telemetry data we collect][telemetry]:
|
|
|
|
| Field | Use |
|
|
| -------------- | ------------------------------------------------------------------------------------------------------ |
|
|
| `distinct_id` | An opaque string that represents your project, by sha256 hashing repository and organization details. |
|
|
| `version` | The version of Nix Flake Checker. |
|
|
| `is_ci` | Whether the checker is being used in CI (GitHub Actions). |
|
|
| `disallowed` | The number of inputs using unsupported branches of Nixpkgs. |
|
|
| `outdated` | The number of inputs using outdated versions of Nixpkgs. |
|
|
| `non_upstream` | The number of inputs using forks of Nixpkgs. |
|
|
|
|
To disable diagnostic reporting, set the diagnostics URL to an empty string by passing `--no-telemetry` or setting `FLAKE_CHECKER_NO_TELEMETRY=true`.
|
|
|
|
You can read the full privacy policy for [Determinate Systems][detsys], the creators of this tool and the [Determinate Nix Installer][installer], [here][privacy].
|
|
|
|
## Rust library
|
|
|
|
The Nix Flake Checker is written in [Rust].
|
|
This repo exposes a [`parse-flake-lock`](./parse-flake-lock) crate that you can use to parse [`flake.lock` files][lockfile] in your own Rust projects.
|
|
To add that dependency:
|
|
|
|
```toml
|
|
[dependencies]
|
|
parse-flake-lock = { git = "https://github.com/DeterminateSystems/flake-checker", branch = "main" }
|
|
```
|
|
|
|
Here's an example usage:
|
|
|
|
```rust
|
|
use std::path::Path;
|
|
|
|
use parse_flake_lock::{FlakeLock, FlakeLockParseError};
|
|
|
|
fn main() -> Result<(), FlakeLockParseError> {
|
|
let flake_lock = FlakeLock::new(Path::new("flake.lock"))?;
|
|
println!("flake.lock info:");
|
|
println!("version: {version}", version=flake_lock.version);
|
|
println!("root node: {root:?}", root=flake_lock.root);
|
|
println!("all nodes: {nodes:?}", nodes=flake_lock.nodes);
|
|
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
The `parse-flake-lock` crate doesn't yet exhaustively parse all input node types, instead using a "fallthrough" mechanism that parses input types that don't yet have explicit struct definitions to a [`serde_json::value::Value`][val].
|
|
If you'd like to help make the parser more exhaustive, [pull requests][prs] are quite welcome.
|
|
|
|
[action]: https://github.com/DeterminateSystems/flake-checker-action
|
|
[detsys]: https://determinate.systems
|
|
[flakes]: https://zero-to-nix.com/concepts/flakes
|
|
[install]: https://zero-to-nix.com/start/install
|
|
[installer]: https://github.com/DeterminateSystems/nix-installer
|
|
[lockfile]: https://zero-to-nix.com/concepts/flakes#lockfile
|
|
[md]: https://github.blog/2022-05-09-supercharging-github-actions-with-job-summaries
|
|
[nixos-org]: https://github.com/NixOS
|
|
[nixpkgs]: https://github.com/NixOS/nixpkgs
|
|
[privacy]: https://determinate.systems/privacy
|
|
[prs]: /pulls
|
|
[rust]: https://rust-lang.org
|
|
[telemetry]: https://github.com/DeterminateSystems/nix-flake-checker/blob/main/src/telemetry.rs#L29-L43
|
|
[val]: https://docs.rs/serde_json/latest/serde_json/value/enum.Value.html
|