mirror of
https://gitlab.com/TECHNOFAB/nix-gitlab-ci.git
synced 2025-12-12 10:10:06 +01:00
technofab
cf80010d07
Squashed commit of the following: commit 86eadd3ec42b7bce0dc5716d65798af95d0d8cbc Author: technofab <admin@technofab.de> Date: Fri May 2 17:10:33 2025 +0200 docs(README): fix built with nix badge commit f50057da69e89974f17bc37b5e140b2ef9f817f6 Author: technofab <admin@technofab.de> Date: Fri May 2 16:09:00 2025 +0200 ci: change back rule so docs only get deployed on main commit ce02b043f4bd83c36285e5620e71701fc3bcc998 Author: technofab <admin@technofab.de> Date: Fri May 2 16:08:10 2025 +0200 docs: write docs and improve formatter etc. commit e996b23cf877d8021759b782aa5996f5e2bf12ac Author: technofab <admin@technofab.de> Date: Fri May 2 16:07:56 2025 +0200 docs: update README commit 650f97b5608c32cf6cf66cc3fdd0965dc42e4860 Author: technofab <admin@technofab.de> Date: Wed Apr 23 21:05:14 2025 +0200 docs: add favicon commit 67e1bfecbcaf0b8f7dad2eecfaccf774cc560874 Author: technofab <admin@technofab.de> Date: Wed Apr 23 20:53:44 2025 +0200 docs: initial setup
59 lines
2.4 KiB
Markdown
59 lines
2.4 KiB
Markdown
# 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.
|