Utilities

Nix GitLab CI provides a couple of utilities to help with development and debugging.

Disabling caching temporarily

Nix GitLab CI often utilizes caching mechanisms to speed up your pipelines (see Caching). However, there might be situations where you need to temporarily disable these caches for a specific pipeline run, for example, to debug a caching issue or ensure a clean build.

To disable most of the provided caches for a pipeline, set the environment variable NIX_CI_DISABLE_CACHE to any non-empty value (e.g., yes, true, 1) when triggering the pipeline in the GitLab UI or via the API.

Forcing a rebuild of the CI pipeline definition

The job responsible for generating the .gitlab-ci.yml from your Nix code (build:nix-ci) might itself be cached. If you've made changes to your Nix CI configuration and the pipeline doesn't seem to pick them up, the cached job definition might be the reason.

You should first double check if all the Nix files you defined the CI config in are specified in the cache_files CI/CD-component input (see CI/CD Component for more).

To force this specific job to rebuild and re-evaluate your Nix configuration, set the environment variable NIX_CI_FORCE_BUILD when triggering the pipeline.

Running jobs locally

One of the benefits of defining your CI jobs with Nix is the ability to run them locally in an environment that closely mirrors the CI environment. This can significantly speed up debugging and development.

You can run the script of any defined job locally using the nix run command. The syntax is:

nix run .#gitlab-ci:pipeline:<pipeline name>:job:<job name>

Replace <pipeline name> with the name of the pipeline the job belongs to (e.g., default for jobs defined under the ci attribute) and <job name> with the name of the job you want to run.

This command will set up the environment with the specified nix.deps and execute the job's script.

There is also an attribute .#gitlab-ci:pipeline:<pipeline name>:job-deps:<job name>. Building this derivation will generate a shell script which exports the required environment variables for the job, such as the PATH including all dependencies and any custom environment variables that contain store paths (ensuring they are correctly resolved across different architectures).

You can use this to inspect the environment that would be set up for a job without running the full script.