nix-gitlab-ci/docs/utilities.md

# 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](./caching.md)).
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](./cicd_component.md) 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:

```sh
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.

## Viewing generated config in YAML

Since the GitLab CI config is generated simply using JSON, it's hard to read and
debug. For debugging V3 now adds another package `gitlab-ci:pipeline:<pipeline name>:pretty`.