nix-gitlab-ci/docs/setup.md

# Setup

To integrate Nix GitLab CI into your project, you need to make two main changes:

1. Add the `nix-gitlab-ci` flake module to your `flake.nix`.
1. Include the necessary component in your `.gitlab-ci.yml`.

## Adding to `flake.nix`

In your project's `flake.nix`, add `nix-gitlab-ci` as an input and import its
flake module within your `flake-parts` configuration.

```nix title="flake.nix"
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; # Or your preferred nixpkgs branch/version
    flake-parts.url = "github:hercules-ci/flake-parts";

    # Add nix-gitlab-ci as an input
    # recommendation: pin to a specific release/version
    nix-gitlab-ci.url = "gitlab:TECHNOFAB/nix-gitlab-ci/<version>?dir=lib";
  };

  outputs = { nixpkgs, flake-parts, ... }@inputs:
    flake-parts.lib.mkFlake { inherit inputs; } {
      imports = [
        # Import the nix-gitlab-ci flake module
        inputs.nix-gitlab-ci.flakeModule
      ];

      systems = [
        "x86_64-linux"
        "aarch64-linux"
        # Add other systems you need
      ];

      perSystem = { pkgs, ... }: {
        # define your CI pipelines
        # ci.pipelines."merge_request_event" = { ... };
      };
    };
}
```

Replace `<version>` with the specific version or commit hash of `nix-gitlab-ci`
you wish to use. Pinning to a specific version is highly recommended for
reproducibility and compatibility.

!!! warning

    While the flake input is locked through `flake.lock`, the CI/CD component
    will always use the latest commit of the reference. This means that by using
    a branch like `main` as version for both, the CI/CD component will always use
    the latest commit while your flake uses a fixed one.
    This could result in drift between both, potentially breaking stuff.

## Including in `.gitlab-ci.yml`

Your `.gitlab-ci.yml` file will be minimal. Its primary role is to include the
`nix-gitlab-ci` component, which will then generate the full CI configuration
based on your Nix code.

```yaml title=".gitlab-ci.yml"
include:
  - component: gitlab.com/TECHNOFAB/nix-gitlab-ci/nix-gitlab-ci@<version>
    inputs:
      # This input sets the Docker image tag used for the CI jobs.
      # Use the same version as you pinned in your flake.nix for consistency.
      version: <version>
```

Again, ensure `<version>` matches the version used in your `flake.nix`.
This component includes a job (`build:nix-ci`) that will evaluate your Nix
configuration and generate the `.gitlab-ci.yml` used for the pipeline run.

!!! note

    Since V3 [Soonix](https://soonix.projects.tf) is supported, this can
    automatically generate the `.gitlab-ci.yml` for you, with the version
    automatically following the flake.
    See [Soonix Integration](./soonix.md) for more.