technofab/nix-gitlab-ci
1
0
Fork 0
mirror of https://gitlab.com/TECHNOFAB/nix-gitlab-ci.git synced 2025-12-12 02:00:13 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: write docs & improve tooling

Browse source 
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
This commit is contained in:
technofab 2025-05-02 17:30:06 +02:00
parent fa6c454b14
commit cf80010d07
15 changed files with 631 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

59
docs/utilities.md Normal file
View file

@ -0,0 +1,59 @@
# 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.