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.
2. 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.

{
  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.

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.