2025-12-12 02:00:13 +01:00 · 2025-09-02 11:49:35 +02:00 · 2025-09-02 11:49:35 +02:00 · 0bd75fd1bb
commit 0bd75fd1bb
parent f147295418
12 changed files with 538 additions and 1 deletions
--- a/docs/setup.md
+++ b/docs/setup.md
@ -0,0 +1,81 @@
+# 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.