Introduction

Omnix aims to supplement the Nix CLI to improve developer experience.

Install

To install Omnix, you first need Nix installed,¹ before running the following:

# Install omnix (using om.cachix.org Nix cache)
nix --accept-flake-config profile install github:juspay/omnix

# Make sure that the `om` command works
om --help

Next Steps

Checkout the CLI commands available.

Discussion

For discussing Omnix, use Github Discussions or Zulip.

The om CLI

The Omnix CLI currently provides a fully-functioning health and ci commands. The show command has basic functionality, whereas the init command is not yet ready for wider use.

Show

The om show command seeks to provide a better nix flake show experience.

Usage

Run om show on any flake - via URL or local path.

$ om show github:srid/nixos-config
🐚 nix --extra-experimental-features 'nix-command flakes' show-config --json️
🐚 /nix/store/n02w2ybg9fc78grzz9i2aj49q3rysp7m-nix-2.24.0pre20240801_af10904/bin/nix flake show --legacy --allow-import-from-derivation --json --default-flake-schemas /nix/store/xzalq6mcw0ahyaccab6k98dbx3ll53y6-source github:srid/nixos-config️
📦 Packages (nix build github:srid/nixos-config#<name>)
╭──────────┬───────────────────────────────────────────────────────╮
│ name     │ description                                           │
├──────────┼───────────────────────────────────────────────────────┤
│ activate │ Activate NixOS/nix-darwin/home-manager configurations │
│ default  │ Activate NixOS/nix-darwin/home-manager configurations │
│ update   │ N/A                                                   │
╰──────────┴───────────────────────────────────────────────────────╯

🐚 Devshells (nix develop github:srid/nixos-config#<name>)
╭─────────┬──────────────────────────────────╮
│ name    │ description                      │
├─────────┼──────────────────────────────────┤
│ default │ Dev environment for nixos-config │
╰─────────┴──────────────────────────────────╯

🔍 Checks (nix flake check)
╭─────────┬─────────────╮
│ name    │ description │
├─────────┼─────────────┤
│ treefmt │ N/A         │
╰─────────┴─────────────╯

🐧 NixOS Configurations (nixos-rebuild switch --flake github:srid/nixos-config#<name>)
╭───────────┬─────────────╮
│ name      │ description │
├───────────┼─────────────┤
│ immediacy │ N/A         │
╰───────────┴─────────────╯

🍏 Darwin Configurations (darwin-rebuild switch --flake github:srid/nixos-config#<name>)
╭────────────┬─────────────╮
│ name       │ description │
├────────────┼─────────────┤
│ appreciate │ N/A         │
╰────────────┴─────────────╯

🔧 NixOS Modules
╭──────────────┬─────────────╮
│ name         │ description │
├──────────────┼─────────────┤
│ common       │ N/A         │
│ default      │ N/A         │
│ home-manager │ N/A         │
│ my-home      │ N/A         │
│ nixosFlake   │ N/A         │
╰──────────────┴─────────────╯

om health

The om health command checks the health of your Nix install. Furthermore, individual projects can configure their own health checks in their flake.nix. For example, the nammayatri project checks that the cachix cache is in use.

Checks performed

Note that some checks are considered non-essential. For eg., the disk space check looks for 1TB+ disk space, but if the user is on a laptop with 256GB SSD, the check will report a warning instead of failing. This can also be configured in per-project basis from flake.nix (see below).

Usage

om health

To run use the health check configuration specified in a project flake, pass that flake as an argument. For eg., to run halth checks defined from the nammayatri project, run:

# The argument can be any flake URL (including a local path)
om health github:nammayatri/nammayatri

Configuring in flake.nix

To add project specific health checks or configure health checks, add the following flake output:

{
  outputs = inputs: {
    om.health.default = {
      # Add configuration here
      caches.required = [ "https://ourproject.cachix.org" ];
    };
  };
}

To see all available configuration options, run om health --dump-schema. This will dump the schema of the configuration in JSON format. Convert that to a Nix attrset to see what can be added under the om.health.default attrset of your flake.

$ om health --dump-schema > schema.json
$ nix eval --impure --expr 'builtins.fromJSON (builtins.readFile ./schema.json)' \
  | nix run nixpkgs#alejandra -- --quiet

This will output:

{
  caches = {required = ["https://cache.nixos.org/"];};
  direnv = {
    enable = true;
    required = false;
  };
  flake-enabled = {};
  max-jobs = {};
  nix-version = {min-required = "2.13.0";};
  rosetta = {
    enable = true;
    required = true;
  };
  system = {
    enable = true;
    min_disk_space = "1024.0 GB";
    min_ram = null;
    required = false;
  };
  trusted-users = {};
}

Adding devShell check

You can automatically run om health whenever your Nix dev shell starts. To do this, import the flake module in your flake and use it in your devShell:

{
  inputs = {
    omnix-flake.url = "github:juspay/omnix?dir=nix/om";
  };
  outputs = inputs:
    inputs.flake-parts.lib.mkFlake { inherit inputs; } {
      imports = [
        inputs.omnix-flake.flakeModules.default
      ];
      perSystem = { config, pkgs, ... }: {
        devShells.default = pkgs.mkShell {
          inputsFrom = [
            config.om.health.outputs.devShell
          ]
        };
      };
    };
}

Now suppose you have Nix 2.18 installed, but your project requires 2.19 or above due to the following config in its flake.nix:

flake.om.health.default = {
  nix-version.min-required = "2.19.0";
};

you can expect the devShell to print a giant message like this:

Note that you will still be dropped into the Nix dev shell (there’s no way to abrupt the launching of a dev Shell).

om ci

om ci runs CI for your project. It builds all outputs in the flake, or optionally its sub-flakes. You can run om ci locally or in an actual CI envirnoment, like GitHub Actions. Using devour-flake it will automatically build the following outputs:

The stdout of om ci run will be a list of store paths built.

Basic Usage

om ci run accepts any valid flake URL or a Github PR URL.

# Run CI on current directory flake
$ om ci # Or `om ci run` or `om ci run .`

# Run CI on a local flake (default is $PWD)
$ om ci run ~/code/myproject

# Run CI on a github repo
$ om ci run github:hercules-ci/hercules-ci-agent

# Run CI on a github PR
$ om ci run https://github.com/srid/emanote/pull/451

# Run CI only the selected sub-flake
$ git clone https://github.com/srid/haskell-flake && cd haskell-flake
$ om ci run .#default.dev

# Run CI remotely over SSH
$ om ci run --on ssh://myname@myserver ~/code/myproject

Using in Github Actions

In addition to serving the purpose of being a “local CI”, om ci can be used in Github Actions to enable CI for your GitHub repositories.

Standard Runners

Add this to your workflow file (.github/workflows/ci.yml) to build all flake outputs using GitHub provided runners:

      - uses: actions/checkout@v4
      - uses: DeterminateSystems/nix-installer-action@main
      - name: Install omnix
        run: nix --accept-flake-config profile install "github:juspay/omnix"
      - run: om ci

Self-hosted Runners with Job Matrix

Here’s a more advanced example that configures a job matrix. This is useful when you want to run the CI on multiple systems (e.g. aarch64-linux, aarch64-darwin), each captured as a separate job by GitHub, as shown in the screenshot below. It also, incidentally, demonstrates how to use self-hosted runners.

The om ci gh-matrix command outputs the matrix JSON for creating a matrix of job variations. An example configuration, using self-hosted runners, is shown below.

# Run on aarch64-linux and aarch64-darwin
jobs:
  configure:
    runs-on: x86_64-linux
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
     - uses: actions/checkout@v4
     - id: set-matrix
       run: echo "matrix=$(om ci gh-matrix --systems=x86_64-linux,aarch64-darwin | jq -c .)" >> $GITHUB_OUTPUT
  nix:
    runs-on: ${{ matrix.system }}
    needs: configure
    strategy:
      matrix: ${{ fromJson(needs.configure.outputs.matrix) }}
      fail-fast: false
    steps:
      - uses: actions/checkout@v4
      - run: om ci run --systems "${{ matrix.system }}" ".#default.${{ matrix.subflake }}"

Configuring

By default, om ci will build the top-level flake, but you can tell it to build sub-flakes (here, ./dir1 and ./dir2) by adding the following output to your top-level flake:

# myproject/flake.nix
{
  om.ci.default = {
    dir1 = {
      dir = "dir1";
    };
    dir2 = {
      dir = "dir2";
      overrideInputs.myproject = ./.;
    };
  }
}

You can have more than one CI configuration. For eg., om ci run .#foo will run the configuration from om.ci.foo flake output.

Custom CI actions

You can define custom CI actions in your flake, which will be run as part of om ci run. For example, to run tests in the nix develop shell:

{
  om.ci.default = {
    root = {
      dir = ".";
      steps = {
        # The build step is enabled by default. It builds all flake outputs.
        build.enable = true;
        # Other steps include: lockfile & flake-check

        # Users can define custom steps to run any arbitrary flake app or devShell command.
        custom = {
          # Here, we run cargo tests in the nix shell
          # This equivalent to `nix develop .#default -c cargo test`
          cargo-test = {
            type = "devshell";
            # name = "default"
            command = [ "cargo" "test" ];
          };

          # We can also flake apps
          # This is equivalent to `nix run .#check-closure-size`
          closure-size = {
            type = "app";
            name = "check-closure-size";
          };
        };
      };
    };
  };
}

For a real-world example of custom steps, checkout Omnix’s configuration.

Examples

Some real-world examples of how om ci is used with specific configurations:

• omnix
• services-flake
• nixos-flake
• haskell-flake
  • Here’s a blog post that talks about how it is used in haskell-flake
• superposition
• haskell-rust-ffi-template

What it does

• Check that the Nix version is not tool old (using om health)
• Determine the list of flakes in the repo to build
  • By default, this is the root flake.
  • The user can also explicitly specify multiple sub-flakes in om.ci.default output of their root flake.
• For each (sub)flake identified, om ci run will run the following steps:
  • Check that flake.lock is up to date, if applicable.
  • Build all flake outputs, using devour-flake¹
    • Then, print the built store paths to stdout
  • Run nix flake check
  • Run user defined custom steps

See also

• github-nix-ci - A simple NixOS & nix-darwin module for self-hosting GitHub runners
• jenkins-nix-ci - Jenkins NixOS module that supports nixci (predecessor of om ci) as a Groovy function
• cachix-push - A flake-parts module that provides an app to enable whitelisted pushing and pinning of store paths to cachix.

om init

The om init command provides a better nix flake init experience. Specifically, it provides:

1. a registry of flake templates that you can choose from
2. support for template paramters that can be filled in by the user

Available templates

Adding your own project templates

In future, you would be able to directly initialize a project from a git repository, viz.: om init <url>. This is explicitly not yet supported right now, because:

Release history

Unreleased

Enhancements

• om health
  • Display Nix installer used (supports DetSys installer)
• om ci
  • Support for remote builds over SSH (via --on option)
  • Support for CI steps
    • Run nix flake check on all subflakes (#200)
    • Ability to add a custom CI step. For example, to run arbitrary commands.
  • Add --results=FILE to store CI results as JSON in a file
  • Misc
    • Avoid running nix-store command multiple times (#224)
    • Locally cache github:nix-systems (to avoid Github API rate limit)

Fixes

• om ci run: The --override-input option mandated flake/ prefix (nixci legacy) which is no longer necessary in this release.
• om health: Use whoami to determine username which is more reliable than relying on USER environment variable

Backward-incompatible changes

• om ci build has been renamed to om ci run.

0.1.0 (2024-08-08)

Initial release of omnix.