docs: add remaining docs back with some additions/improvements

docs/utilities.md

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