GitLab CI - Mic92/niks3 GitHub Wiki

Using niks3 with GitLab CI

This guide shows how to push Nix build outputs to niks3 from GitLab CI using OIDC authentication.

Server Setup

Configure your niks3 server to accept GitLab CI OIDC tokens. See OIDC for general configuration.

GitLab CI provider example:

{
  services.niks3.oidc.providers.gitlab = {
    issuer = "https://gitlab.com";  # or your self-hosted GitLab URL
    audience = "https://niks3.example.com";
    boundClaims = {
      namespace_path = [ "your-org" ];
    };
  };
}

Pipeline

stages:
  - build

variables:
  NIX_CONFIG: |
    extra-substituters = https://cache.example.com
    extra-trusted-public-keys = my-cache-1:base64encodedpublickey...

build:
  stage: build
  image: nixos/nix:latest
  id_tokens:
    NIKS3_TOKEN:
      aud: https://niks3.example.com
  script:
    - nix build --log-format bar-with-logs --extra-experimental-features "nix-command flakes"
    - |
      curl -fsSL "https://github.com/Mic92/niks3/releases/latest/download/niks3_$(uname -s)_$(uname -m).tar.gz" | tar -xzf -
      ./niks3 push \
        --server-url https://niks3.example.com \
        --auth-token "$NIKS3_TOKEN" \
        ./result
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Key Points

  • The id_tokens keyword generates OIDC tokens with the specified audience
  • NIKS3_TOKEN environment variable contains the JWT token
  • The aud parameter must match the server configuration

GitLab CI Claims

Use these claims for access control in boundClaims:

Claim Example Description
namespace_path mygroup Group or user namespace
project_path mygroup/myproject Full project path
ref main Branch or tag name
ref_type branch Type: branch or tag
ref_protected true Whether ref is protected

Example restricting to protected branches:

{
  services.niks3.oidc.providers.gitlab = {
    issuer = "https://gitlab.com";
    audience = "https://niks3.example.com";
    boundClaims = {
      namespace_path = [ "your-org" ];
      ref_protected = [ "true" ];
    };
  };
}

Self-Hosted GitLab

For self-hosted GitLab instances, use your GitLab URL as the issuer:

{
  services.niks3.oidc.providers.gitlab = {
    issuer = "https://gitlab.yourcompany.com";
    audience = "https://niks3.example.com";
    boundClaims = {
      namespace_path = [ "your-org" ];
    };
  };
}

Alternative: Using Nix

Instead of downloading the binary:

      - |
        nix build -o niks3 github:Mic92/niks3 --extra-experimental-features "nix-command flakes"
        niks3/bin/niks3 push \
          --server-url https://niks3.example.com \
          --auth-token "$NIKS3_TOKEN" \
          ./result ./niks3

This also pushes niks3 itself to the cache, which can speed up future runs.

Real-World Example