Nix CI

https://nix-ci.com/documentation
Admin
Nix CI is a continuous integration and deployment service specifically designed for Nix projects,...
Tokens:6,944
Snippets:56
Trust Score:5.1
Update:7 months ago
Show doc for...
Tokens:
Raw
### Example Flake Outputs for NixCI (Nix)

Source: https://nix-ci.com/documentation/what-gets-built

Demonstrates a typical structure of flake outputs for a specific system (x86_64-linux) that NixCI will process. This includes various types of outputs like devShell, packages, and checks.

```nix
{
  devShell.x86_64-linux = ...;
  devShells.x86_64-linux.default = ...;
  formatter.x86_64-linux = ...;
  packages.x86_64-linux.default = ...;
  packages.x86_64-linux.my-app = ...;
  checks.x86_64-linux.lint = ...;
  checks.x86_64-linux.tests = ...;
}

```

--------------------------------

### Example NixCI Test Configuration

Source: https://nix-ci.com/documentation/test

This NixCI configuration snippet demonstrates how to set up an impure test. It specifies the 'packages.x86_64-linux.impure-test' package to be executed as a test on the default branch.

```nix
{
  test = {
    example = {
      branches = "default";
      package = "packages.x86_64-linux.impure-test";
    };
  };
}

```

--------------------------------

### Exposing NixOS Configurations as Checks in NixCI (Nix)

Source: https://nix-ci.com/documentation/what-gets-built

Shows how to expose a NixOS configuration as a check within NixCI, as NixCI cannot automatically determine the architecture for direct builds. This allows NixOS configurations to be built and tested.

```nix
checks.x86_64-linux.my-machine =
  nixosConfigurations.my-machine.config.system.build.toplevel;

```

--------------------------------

### Validate Nix-CI Configuration with nix eval

Source: https://nix-ci.com/documentation/configuration

This command evaluates your local nix-ci.nix file and outputs its configuration as a JSON string. This is useful for validating your configuration before committing changes. It requires the Nix package manager to be installed.

```bash
nix eval --json --file ./nix-ci.nix
```

--------------------------------

### Use SSH Key in Shell Command

Source: https://nix-ci.com/documentation/secrets

This shell command example shows how to use an SSH key provided by NixCI. The environment variable 'CI_SSH_KEY' holds the path to the temporary SSH key file, which can be used with the '-i' option for SSH connections.

```bash
ssh -i "$CI_SSH_KEY" user@server
```

--------------------------------

### Generate NixCI Badge URL

Source: https://nix-ci.com/documentation/badges

This snippet shows the pattern for generating a NixCI badge URL. It includes examples for a general badge and a per-branch badge. The repository identifier is a key input.

```text
https://nix-ci.com/badge/gh:NorfairKing:nix-ci
https://nix-ci.com/badge/gh:NorfairKing:nix-ci/mybranch
```

--------------------------------

### Configure NixCI Cache Substituter

Source: https://nix-ci.com/documentation/nix-ci-cache

Explains how to configure Nix to use the NixCI cache as a substituter. This allows Nix to download pre-built binaries from the cache, speeding up builds.

```nix
nix.settings.substituters = ["https://cache.nix-ci.com"];
```

--------------------------------

### Push to NixCI Cache with nix copy

Source: https://nix-ci.com/documentation/nix-ci-cache

Shows how to manually push build artifacts to the NixCI cache using the `nix copy` command. This allows you to make your built packages available in the cache for others to use.

```shell
nix copy ./result --to  https://cache.nix-ci.com
```

```shell
nix copy .#yourPackage --to  https://cache.nix-ci.com
```

--------------------------------

### Pull from NixCI Cache

Source: https://nix-ci.com/documentation/nix-ci-cache

Demonstrates how to pull packages from the NixCI cache. This command attempts to retrieve a specific package from the configured cache substituter.

```shell
nix copy --from https://cache.nix-ci.com $(nix path-info github:nixos/nixpkgs#hello)
```

--------------------------------

### Configure NixCI Cache in Flake

Source: https://nix-ci.com/documentation/nix-ci-cache

Shows how to configure the NixCI cache substituter and trusted public key within a Nix flake for per-flake caching. This provides a convenient way to manage cache settings for individual projects.

```nix
nixConfig = {
  extra-substituters = "https://cache.nix-ci.com";
  extra-trusted-public-keys = "nix-ci:g3xV5BDTLtIBZr/A00IU1x0EtKKlb7YLgBN2SgYgM6A=";
};

```

--------------------------------

### Trust NixCI Signing Key

Source: https://nix-ci.com/documentation/nix-ci-cache

Details how to trust the NixCI signing key to verify the integrity of build outputs from the cache. This is crucial for ensuring that the binaries you download have not been tampered with.

```nix
nix.settings.trusted-public-keys = ["nix-ci:g3xV5BDTLtIBZr/A00IU1x0EtKKlb7YLgBN2SgYgM6A="];
```

--------------------------------

### Configure Deployment Package in NixCI

Source: https://nix-ci.com/documentation/deploy

This snippet shows how to add a 'deploy' section to your NixCI configuration to specify a package for deployment. NixCI will execute the 'meta.mainProgram' of the specified package.

```nix
{
  deploy = {
    example = {
      package = "packages.x86_64-linux.deploy-to-prod";
    };
  };
}

```

--------------------------------

### Authenticate NixCI Cache with curl

Source: https://nix-ci.com/documentation/nix-ci-cache

Demonstrates how to authenticate with the NixCI cache using curl and a netrc file. This involves setting up the netrc file with user credentials and then using the `--netrc` flag with curl to access the cache.

```shell
curl https://cache.nix-ci.com/nix-cache-info
curl --netrc https://cache.nix-ci.com/nix-cache-info
```

--------------------------------

### NixCI Production Worker Configuration

Source: https://nix-ci.com/documentation/self-hosting/nixos/worker

Configuration options for enabling and customizing NixCI production workers.

```APIDOC
## NixCI Production Worker Configuration

### Description
Configure the production workers for NixCI, including enabling them, setting up recommended OS settings, and defining individual worker configurations.

### Method
N/A (Configuration Options)

### Endpoint
N/A (Configuration Options)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A

## NixOS Module Options

### `services.nix-ci.production.worker.enable`
Enable the NixCI Workers.

- **Type**: `boolean`
- **Default**: `true`
- **Example**: `false`

### `services.nix-ci.production.worker.recommendedOSSettings`
Enable recommended OS settings.

- **Type**: `boolean`
- **Default**: `true`
- **Example**: `false`

### `services.nix-ci.production.worker.workers`
Configuration for individual workers.

- **Type**: `attribute set of (submodule)`

#### `services.nix-ci.production.worker.workers.<name>.auto-wipe`
Remove the VM state on every boot, for truly ephemeral workers.

- **Type**: `boolean`
- **Default**: `true`

#### `services.nix-ci.production.worker.workers.<name>.cache-subdir`
Cache directory of the worker, this is where the VM state is stored.

- **Type**: `null or string`
- **Default**: `"nix-ci-production-worker/‹name›"`

#### `services.nix-ci.production.worker.workers.<name>.debug`
Enable or configure debug options for the worker.

- **Type**: `null or (submodule)`
- **Default**: `null`

##### `services.nix-ci.production.worker.workers.<name>.debug.authorizedKeysFiles`
SSH public key files with which the host can ssh into the VM.

- **Type**: `list of string`
- **Default**: `[ ]`

##### `services.nix-ci.production.worker.workers.<name>.debug.enable`
Whether to enable NixCI Worker debug options.

- **Type**: `boolean`
- **Default**: `false`
- **Example**: `true`

##### `services.nix-ci.production.worker.workers.<name>.debug.port`
Port to ssh into the VM.

- **Type**: `16 bit unsigned integer; between 0 and 65535 (both inclusive)`
- **Default**: `2222`

##### `services.nix-ci.production.worker.workers.<name>.debug.rootPassword`
Root password for debugging.

- **Type**: `string`
- **Default**: `"root"`

#### `services.nix-ci.production.worker.workers.<name>.enable`
Enable the worker: ‹name›.

- **Type**: `boolean`
- **Default**: `true`

#### `services.nix-ci.production.worker.workers.<name>.extraServiceConfig`
Extra options in the worker VM's ServiceConfig.

- **Type**: `unspecified value`
- **Default**: `{ }`

#### `services.nix-ci.production.worker.workers.<name>.gateway`
The gateway to allow access to.

- **Type**: `null or string`
- **Default**: `null`
- **Example**: `"10.0.0.0"`

#### `services.nix-ci.production.worker.workers.<name>.guest-imports`

- **Type**: `unspecified value`
- **Default**: `[ ]`

#### `services.nix-ci.production.worker.workers.<name>.hostName`
Hostname for the guest vm.

- **Type**: `null or string`
- **Default**: `null`

#### `services.nix-ci.production.worker.workers.<name>.local-network`
The local network to deny access to.

- **Type**: `null or string`
- **Default**: `null`
- **Example**: `"10.0.0.0/8"`

#### `services.nix-ci.production.worker.workers.<name>.virtualisation`

- **Type**: `unspecified value`

#### `services.nix-ci.production.worker.workers.<name>.workers`

- **Type**: `attribute set of (submodule)`
- **Default**: `{ }`

##### `services.nix-ci.production.worker.workers.<name>.workers.<name>.auto-reboot`
Automatically reboot the worker machine if the worker service crashes.

- **Type**: `boolean`
- **Default**: `true`
- **Example**: `false`

##### `services.nix-ci.production.worker.workers.<name>.workers.<name>.config`

- **Type**: `submodule`
- **Default**: `{ }`

###### `services.nix-ci.production.worker.workers.<name>.workers.<name>.config.allowed`
Allowed work.

- **Type**: `null or (submodule) or list of (submodule)`
- **Default**: `null`

###### `services.nix-ci.production.worker.workers.<name>.workers.<name>.config.cachix-executable`
Path to the cachix executable.

- **Type**: `null or string`
- **Default**: `null`

###### `services.nix-ci.production.worker.workers.<name>.workers.<name>.config.git-executable`
Path to the git executable.

- **Type**: `null or string`
- **Default**: `null`

###### `services.nix-ci.production.worker.workers.<name>.workers.<name>.config.leader`
Leader API.

- **Type**: `null or string`
- **Default**: `null`

###### `services.nix-ci.production.worker.workers.<name>.workers.<name>.config.log-level`
Minimal severity of log messages.

- **Type**: `null or one of "Debug", "Info", "Warn", "Error"`
- **Default**: `null`

###### `services.nix-ci.production.worker.workers.<name>.workers.<name>.config.name`
Worker name for registering with the leader.

- **Type**: `null or string`
- **Default**: `null`

###### `services.nix-ci.production.worker.workers.<name>.workers.<name>.config.nix-executable`
Path to the nix executable.

- **Type**: `null or string`
- **Default**: `null`

###### `services.nix-ci.production.worker.workers.<name>.workers.<name>.config.private-key`
Worker private key for authenticating with the leader.

- **Type**: `null or string`
- **Default**: `null`

###### `services.nix-ci.production.worker.workers.<name>.workers.<name>.config.private-key-file`
Worker private key for authenticating with the leader.

- **Type**: `null or string`
- **Default**: `null`

```

--------------------------------

### NixCI Deployment Configuration Schema

Source: https://nix-ci.com/documentation/deploy

This is the reference schema for NixCI deployment configurations. It outlines optional and required fields such as 'enable', 'package', 'system', 'branches', 'secrets', and 'ssh-keys'.

```yaml
deploy: # optional
  # default: {}
  # Deploy Configurations
  <key>: 
    # DeployConfiguration
    enable: # optional
      # default: true
      # enable this deployment
      <boolean>
    package: # required
      # package of which the main program will be run
      <string>
    system: # optional
      # system on which the deployment will be run
      <string>
    branches: # optional
      # default: default
      # branches from which may be deployed
      # any of
      [ # Deploy from any branch
        any
      , # The same as "any"
        all
      , # Only deploy from the default branch
        default
      , # Deploy from any of this list of branches
        - <string>
      ]
    secrets: # optional
      # default: []
      # secrets provided to the deployment
      - <string>
    ssh-keys: # optional
      # default: []
      # ssh keys provided to the deployment
      - # SshKeyConfiguration
        secret: # required
          # name of the secret on NixCI to use as the private key
          <string>
        public-key: # required
          # public key of the ssh key
          <string>

```

--------------------------------

### Configure Git SSH Key in NixCI

Source: https://nix-ci.com/documentation/git-ssh-key

This snippet shows the TOML configuration for setting up a Git SSH key in NixCI. It specifies the public key and the name of the secret that holds the private key.

```toml
{
  git-ssh-key = {
    public-key = "my pubkey here";
    secret = "GIT_SSH_KEY";
  };
}

```

--------------------------------

### Generate NixCI Worker Key

Source: https://nix-ci.com/documentation/self-hosting/worker-keygen

This command generates a worker key for NixCI authentication. It uses `nix run` to execute the `worker-keygen` app directly from the specified Git repository. No specific inputs are required, and the output is the generated worker key.

```bash
nix run git+ssh://git@github.com/NorfairKing/nix-ci.git#worker-keygen
```

--------------------------------

### Configure NixCI Cache Netrc File

Source: https://nix-ci.com/documentation/nix-ci-cache

Provides instructions for configuring the netrc file for NixCI cache authentication. This includes setting the `nix.settings.netrc-file` option on NixOS and the `netrc-file` setting in `nix.conf` for other systems.

```nix
nix.settings.netrc-file = "/home/user/.netrc"
```

```nix
netrc-file = /home/user/.netrc
```

--------------------------------

### Cachix Configuration Schema (Nix)

Source: https://nix-ci.com/documentation/cachix

This snippet outlines the reference schema for Cachix configuration within Nix. It details the required `name` and `public-key` fields for cache integration and mentions the optional requirement of `CACHIX_AUTH_TOKEN` or `CACHIX_SIGNING_KEY` secrets for pushing to the cache.

```nix
cachix: # optional
  # Cachix configuration
  # In order to push to the cache as well, the repository needs to have a CACHIX_AUTH_TOKEN or CACHIX_SIGNING_KEY secret.
  # CachixConfiguration
  name: # required
    # cache name
    <string>
  public-key: # required
    # cache public key (for pulling)
    <string>

```

--------------------------------

### Configure NixCI Cachix Integration (Nix)

Source: https://nix-ci.com/documentation/cachix

This snippet shows how to configure NixCI to integrate with Cachix by specifying the cache name and public key in your flake's nix-ci.cachix configuration. This enables NixCI to pull from your Cachix cache.

```nix
{
  cachix = {
    name = "foo-bar";
    public-key = "foo-bar.cachix.org-1:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };
}

```

--------------------------------

### NixCI Git SSH Key Schema Reference

Source: https://nix-ci.com/documentation/git-ssh-key

This snippet provides the schema definition for the `git-ssh-key` configuration in NixCI. It outlines the required `secret` and `public-key` fields and their types.

```nix
git-ssh-key: # optional
  # SSH Key to use for git-clone-ing
  # By default no SSH key is used so Nix will fail to clone private dependencies.
  # SshKeyConfiguration
  secret: # required
    # name of the secret on NixCI to use as the private key
    <string>
  public-key: # required
    # public key of the ssh key
    <string>

```

--------------------------------

### NixCI Test Configuration Schema

Source: https://nix-ci.com/documentation/test

This is a reference schema for configuring tests in NixCI. It outlines the available options for enabling tests, specifying packages, systems, branches, and managing secrets and SSH keys.

```nix
test: # optional
  # default: {}
  # Test Configurations
  <key>: 
    # TestConfiguration
    enable: # optional
      # default: true
      # enable this test
      <boolean>
    package: # required
      # package of which the main program will be run
      <string>
    system: # optional
      # system on which the test will be run
      <string>
    branches: # optional
      # default: any
      # branches from which may be tested
      # any of
      [ # Deploy from any branch
        any
      , # The same as "any"
        all
      , # Only deploy from the default branch
        default
      , # Deploy from any of this list of branches
        - <string>
      ]
    secrets: # optional
      # default: []
      # secrets provided to the test
      - <string>
    ssh-keys: # optional
      # default: []
      # ssh keys provided to the test
      - # SshKeyConfiguration
        secret: # required
          # name of the secret on NixCI to use as the private key
          <string>
        public-key: # required
          # public key of the ssh key
          <string>


```

--------------------------------

### Declare SSH Key for NixCI Deployment

Source: https://nix-ci.com/documentation/secrets

This Nix code snippet demonstrates how to declare an SSH key for a deployment job in NixCI. The 'CI_SSH_KEY' secret is treated as an SSH key, and NixCI will provide its path as an environment variable.

```nix
{
  deploy = {
    example = {
      package = "packages.x86_64-linux.deploy-to-prod";
      ssh-keys = [{
        public-key = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOJSjGhDsCpOGTldxNvLP3NCM1eLMNxjHKKg4y2my1PS";
        secret = "CI_SSH_KEY";
      }];
    };
  };
}
```

--------------------------------

### Add NixCI Badge to HTML

Source: https://nix-ci.com/documentation/badges

This snippet shows how to include a NixCI badge in an HTML file. It utilizes the `<img>` tag with the badge URL assigned to the `src` attribute.

```html
<img src="https://nix-ci.com/badge/gh:NorfairKing:nix-ci" alt="NixCI Badge">
```

--------------------------------

### Declare SSH Key for NixCI Test

Source: https://nix-ci.com/documentation/secrets

This Nix code snippet illustrates how to declare an SSH key for an impure test in NixCI. The 'CI_SSH_KEY' secret is configured as an SSH key, and NixCI will manage its secure handling as a temporary file.

```nix
{
  test = {
    example = {
      branches = "default";
      package = "packages.x86_64-linux.impure-test";
      ssh-keys = [{
        public-key = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOJSjGhDsCpOGTldxNvLP3NCM1eLMNxjHKKg4y2my1PS";
        secret = "CI_SSH_KEY";
      }];
    };
  };
}
```

--------------------------------

### Declare Secret for NixCI Deployment

Source: https://nix-ci.com/documentation/secrets

This Nix code snippet shows how to declare a secret named 'FORGE_ACCESS_TOKEN' for a deployment job in NixCI. The secret will be accessible as an environment variable during the deployment process.

```nix
{
  deploy = {
    example = {
      package = "packages.x86_64-linux.deploy-to-prod";
      secrets = ["FORGE_ACCESS_TOKEN"];
    };
  };
}
```

--------------------------------

### Add NixCI Badge to Markdown

Source: https://nix-ci.com/documentation/badges

This snippet demonstrates how to embed a NixCI badge into a markdown file. It uses standard markdown image syntax with the generated badge URL.

```markdown
![NixCI Badge](https://nix-ci.com/badge/gh:NorfairKing:nix-ci)
```

--------------------------------

### Declare Secret for NixCI Test

Source: https://nix-ci.com/documentation/secrets

This Nix code snippet demonstrates how to declare a secret named 'FORGE_ACCESS_TOKEN' for an impure test job in NixCI. The secret will be available as an environment variable during the test execution.

```nix
{
  test = {
    example = {
      branches = "default";
      package = "packages.x86_64-linux.impure-test";
      secrets = ["FORGE_ACCESS_TOKEN"];
    };
  };
}
```
Tokens:
Raw