# Nix GitLab CI

[![built with nix](https://img.shields.io/static/v1?logo=nixos&logoColor=white&label=&message=Built%20with%20Nix&color=41439a)](https://builtwithnix.org)
[![pipeline status](https://gitlab.com/TECHNOFAB/nix-gitlab-ci/badges/main/pipeline.svg)](https://gitlab.com/TECHNOFAB/nix-gitlab-ci/-/commits/main)
![License: MIT](https://img.shields.io/gitlab/license/technofab/nix-gitlab-ci)
[![Latest Release](https://gitlab.com/TECHNOFAB/nix-gitlab-ci/-/badges/release.svg)](https://gitlab.com/TECHNOFAB/nix-gitlab-ci/-/releases)
[![Support me](https://img.shields.io/badge/Support-me-orange)](https://tec.tf/#support)
[![Docs](https://img.shields.io/badge/Read-Docs-orange)](https://nix-gitlab-ci.projects.tf)

Flake module which allows generating a `.gitlab-ci.yml` from Nix.

This allows easily using any Nix package in CI.

Also makes it possible to split CI parts in a separate module which can be imported in multiple projects.

## Usage (with flake-parts)

```nix
# flake.nix
{
  ...
  inputs.nix-gitlab-ci.url = "gitlab:TECHNOFAB/nix-gitlab-ci/<version>?dir=lib";  # recommendation: pin to the latest release/version
  
  outputs = {...}: flake-parts.lib.mkFlake {...} {
    imports = [
      inputs.nix-gitlab-ci.flakeModule
    ];
    ...
    
    perSystem = {pkgs, ...}: {
      ci = {
        config = {
          # configure Nix-GitLab-CI here, see docs for options
        };
        pipelines."default" = {
          stages = ["test"];
          jobs = {
            "test" = {
              stage = "test";
              nix.deps = [pkgs.unixtools.ping];
              script = [
                "ping -c 5 8.8.8.8"
              ];
            };
          };
        };
        # runs on a merge request for example
        pipelines."merge_request_event" = {
          stages = ["some_stage"];
          jobs = { ... };
        };
      };
      ...
    }
  }
}
```

Now either use this in your .gitlab-ci.yml or setup Soonix to auto generate this
file for you with the right version (see the [docs][docs-soonix] for more).

```yaml
# .gitlab-ci.yml
include:
  - component: gitlab.com/TECHNOFAB/nix-gitlab-ci/nix-gitlab-ci@<version>  # recommendation: pin to the latest release/version (don't use "main" etc.)
    inputs:
      version: <version>  # docker image tag, use the same version as a above
```

## Usage (directly)

```nix
let
  cilib = inputs.nix-gitlab-ci.lib {inherit pkgs;};
in
  cilib.mkCI {
    config = ...;
    pipelines."default" = ...;
  };
  # exposes `soonix` for the soonix hook and `packages` which contain the configs, jobs etc.
```

## Utilities

### Disable Caching temporarily

To disable any of the provided caches for a pipeline one can set `NIX_CI_DISABLE_CACHE` to
anything non-empty (eg. "yes") when triggering the pipeline.

The `build:nix-ci` job has a different special environment variable `NIX_CI_FORCE_BUILD`
(useful if the generated pipeline in the cache is outdated, this will build it again).

### Run Jobs locally

You can run any job's script (+ before and after) locally with Nix for easier testing:

```sh
#                                /  pipeline name, like "default"
nix run .#gitlab-ci:pipeline:<pipeline name>:job:<name>
```

There is also `.#gitlab-ci:pipeline:<pipeline name>:job-deps:<name>` which generates and exports the required environment variables for each job:

- PATH (with all deps)
- any custom env variables which contain store paths to not break stuff when switching archs

## Thanks to

Some parts of this implementation are adapted/inspired from https://gitlab.com/Cynerd/gitlab-ci-nix

[docs-soonix]: https://nix-gitlab-ci.projects,tf/soonix "Soonix Integration"