From e65131e69cab1b18fb49b572b983a18720502e1b Mon Sep 17 00:00:00 2001 From: Emily Date: Thu, 22 Jun 2023 12:21:32 +0100 Subject: treewide: convert all option docs to Markdown This process was automated by [my fork of `nix-doc-munge`]; thanks to @pennae for writing this tool! It automatically checks that the resulting documentation doesn't change, although my fork loosens this a little to ignore some irrelevant whitespace and typographical differences. As of this commit there is no DocBook remaining in the options documentation. You can play along at home if you want to reproduce this commit: $ NIX_PATH=nixpkgs=flake:nixpkgs/c1bca7fe84c646cfd4ebf3482c0e6317a0b13f22 \ nix shell nixpkgs#coreutils \ -c find . -name '*.nix' \ -exec nix run github:emilazy/nix-doc-munge/0a7190f600027bf7baf6cb7139e4d69ac2f51062 \ {} + [my fork of `nix-doc-munge`]: https://github.com/emilazy/nix-doc-munge --- modules/services/gitlab-runner.nix | 112 ++++++++++++++++++------------------- 1 file changed, 56 insertions(+), 56 deletions(-) (limited to 'modules/services/gitlab-runner.nix') diff --git a/modules/services/gitlab-runner.nix b/modules/services/gitlab-runner.nix index b7b50bb..7651ba5 100644 --- a/modules/services/gitlab-runner.nix +++ b/modules/services/gitlab-runner.nix @@ -117,19 +117,19 @@ let in { options.services.gitlab-runner = { - enable = mkEnableOption "Gitlab Runner"; + enable = mkEnableOption (lib.mdDoc "Gitlab Runner"); configFile = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Configuration file for gitlab-runner. - takes precedence over . - and will be ignored too. + {option}`configFile` takes precedence over {option}`services`. + {option}`checkInterval` and {option}`concurrent` will be ignored too. - This option is deprecated, please use instead. - You can use and - + This option is deprecated, please use {option}`services` instead. + You can use {option}`registrationConfigFile` and + {option}`registrationFlags` for settings not covered by this module. ''; }; @@ -137,18 +137,18 @@ in type = types.int; default = 0; example = literalExpression "with lib; (length (attrNames config.services.gitlab-runner.services)) * 3"; - description = '' + description = lib.mdDoc '' Defines the interval length, in seconds, between new jobs check. The default value is 3; if set to 0 or lower, the default value will be used. - See runner documentation for more information. + See [runner documentation](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#how-check_interval-works) for more information. ''; }; concurrent = mkOption { type = types.int; default = 1; example = literalExpression "config.nix.maxJobs"; - description = '' + description = lib.mdDoc '' Limits how many jobs globally can be run concurrently. The most upper limit of jobs using all defined runners. 0 does not mean unlimited. @@ -158,7 +158,7 @@ in type = types.nullOr types.str; default = null; example = "https://public:private@host:port/1"; - description = '' + description = lib.mdDoc '' Data Source Name for tracking of all system level errors to Sentry. ''; }; @@ -166,7 +166,7 @@ in type = types.nullOr types.str; default = null; example = "localhost:8080"; - description = '' + description = lib.mdDoc '' Address (<host>:<port>) on which the Prometheus metrics HTTP server should be listening. ''; @@ -178,7 +178,7 @@ in type = types.nullOr types.str; default = null; example = "0.0.0.0:8093"; - description = '' + description = lib.mdDoc '' An internal URL to be used for the session server. ''; }; @@ -186,16 +186,16 @@ in type = types.nullOr types.str; default = null; example = "runner-host-name.tld:8093"; - description = '' + description = lib.mdDoc '' The URL that the Runner will expose to GitLab to be used to access the session server. - Fallbacks to if not defined. + Fallbacks to {option}`listenAddress` if not defined. ''; }; sessionTimeout = mkOption { type = types.int; default = 1800; - description = '' + description = lib.mdDoc '' How long in seconds the session can stay active after the job completes (which will block the job from finishing). ''; @@ -208,16 +208,16 @@ in listenAddress = "0.0.0.0:8093"; } ''; - description = '' + description = lib.mdDoc '' The session server allows the user to interact with jobs that the Runner is responsible for. A good example of this is the - interactive web terminal. + [interactive web terminal](https://docs.gitlab.com/ee/ci/interactive_web_terminal/index.html). ''; }; gracefulTermination = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Finish all remaining jobs before stopping. If not set gitlab-runner will stop immediatly without waiting for jobs to finish, which will lead to failed builds. @@ -227,7 +227,7 @@ in type = types.str; default = "infinity"; example = "5min 20s"; - description = '' + description = lib.mdDoc '' Time to wait until a graceful shutdown is turned into a forceful one. ''; }; @@ -236,17 +236,17 @@ in default = pkgs.gitlab-runner; defaultText = "pkgs.gitlab-runner"; example = literalExpression "pkgs.gitlab-runner_1_11"; - description = "Gitlab Runner package to use."; + description = lib.mdDoc "Gitlab Runner package to use."; }; extraPackages = mkOption { type = types.listOf types.package; default = [ ]; - description = '' + description = lib.mdDoc '' Extra packages to add to PATH for the gitlab-runner process. ''; }; services = mkOption { - description = "GitLab Runner services."; + description = lib.mdDoc "GitLab Runner services."; default = { }; example = literalExpression '' { @@ -328,27 +328,27 @@ in options = { registrationConfigFile = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Absolute path to a file with environment variables used for gitlab-runner registration. A list of all supported environment variables can be found in - gitlab-runner register --help. + `gitlab-runner register --help`. Ones that you probably want to set is - CI_SERVER_URL=<CI server URL> + `CI_SERVER_URL=` - REGISTRATION_TOKEN=<registration secret> + `REGISTRATION_TOKEN=` ''; }; registrationFlags = mkOption { type = types.listOf types.str; default = [ ]; example = [ "--docker-helper-image my/gitlab-runner-helper" ]; - description = '' + description = lib.mdDoc '' Extra command-line flags passed to - gitlab-runner register. - Execute gitlab-runner register --help + `gitlab-runner register`. + Execute `gitlab-runner register --help` for a list of supported flags. ''; }; @@ -356,25 +356,25 @@ in type = types.attrsOf types.str; default = { }; example = { NAME = "value"; }; - description = '' + description = lib.mdDoc '' Custom environment variables injected to build environment. - For secrets you can use - with RUNNER_ENV variable set. + For secrets you can use {option}`registrationConfigFile` + with `RUNNER_ENV` variable set. ''; }; executor = mkOption { type = types.str; default = "docker"; - description = '' + description = lib.mdDoc '' Select executor, eg. shell, docker, etc. - See runner documentation for more information. + See [runner documentation](https://docs.gitlab.com/runner/executors/README.html) for more information. ''; }; buildsDir = mkOption { type = types.nullOr types.path; default = null; example = "/var/lib/gitlab-runner/builds"; - description = '' + description = lib.mdDoc '' Absolute path to a directory where builds will be stored in context of selected executor (Locally, Docker, SSH). ''; @@ -383,14 +383,14 @@ in type = types.nullOr types.str; default = null; example = "http://gitlab.example.local"; - description = '' + description = lib.mdDoc '' Overwrite the URL for the GitLab instance. Used if the Runner can’t connect to GitLab on the URL GitLab exposes itself. ''; }; dockerImage = mkOption { type = types.nullOr types.str; default = null; - description = '' + description = lib.mdDoc '' Docker image to be used. ''; }; @@ -398,7 +398,7 @@ in type = types.listOf types.str; default = [ ]; example = [ "/var/run/docker.sock:/var/run/docker.sock" ]; - description = '' + description = lib.mdDoc '' Bind-mount a volume and create it if it doesn't exist prior to mounting. ''; @@ -406,14 +406,14 @@ in dockerDisableCache = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Disable all container caching. ''; }; dockerPrivileged = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Give extended privileges to container. ''; }; @@ -421,7 +421,7 @@ in type = types.listOf types.str; default = [ ]; example = [ "other-host:127.0.0.1" ]; - description = '' + description = lib.mdDoc '' Add a custom host-to-IP mapping. ''; }; @@ -429,7 +429,7 @@ in type = types.listOf types.str; default = [ ]; example = [ "ruby:*" "python:*" "php:*" "my.registry.tld:5000/*:*" ]; - description = '' + description = lib.mdDoc '' Whitelist allowed images. ''; }; @@ -437,21 +437,21 @@ in type = types.listOf types.str; default = [ ]; example = [ "postgres:9" "redis:*" "mysql:*" ]; - description = '' + description = lib.mdDoc '' Whitelist allowed services. ''; }; preCloneScript = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Runner-specific command script executed before code is pulled. ''; }; preBuildScript = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Runner-specific command script executed after code is pulled, just before build executes. ''; @@ -459,7 +459,7 @@ in postBuildScript = mkOption { type = types.nullOr types.path; default = null; - description = '' + description = lib.mdDoc '' Runner-specific command script executed after code is pulled and just after build executes. ''; @@ -467,22 +467,22 @@ in tagList = mkOption { type = types.listOf types.str; default = [ ]; - description = '' + description = lib.mdDoc '' Tag list. ''; }; runUntagged = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' Register to run untagged builds; defaults to - true when is empty. + `true` when {option}`tagList` is empty. ''; }; limit = mkOption { type = types.int; default = 0; - description = '' + description = lib.mdDoc '' Limit how many jobs can be handled concurrently by this service. 0 (default) simply means don't limit. ''; @@ -490,14 +490,14 @@ in requestConcurrency = mkOption { type = types.int; default = 0; - description = '' + description = lib.mdDoc '' Limit number of concurrent requests for new jobs from GitLab. ''; }; maximumTimeout = mkOption { type = types.int; default = 0; - description = '' + description = lib.mdDoc '' What is the maximum timeout (in seconds) that will be set for job when using this Runner. 0 (default) simply means don't limit. ''; @@ -505,7 +505,7 @@ in protected = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' When set to true Runner will only run on pipelines triggered on protected branches. ''; @@ -513,9 +513,9 @@ in debugTraceDisabled = mkOption { type = types.bool; default = false; - description = '' + description = lib.mdDoc '' When set to true Runner will disable the possibility of - using the CI_DEBUG_TRACE feature. + using the `CI_DEBUG_TRACE` feature. ''; }; }; -- cgit v1.2.3