id       = "gitlab-runner"
name     = "GitLab Runner"
homepage = "https://docs.gitlab.com/runner/"
description = "An application that works with GitLab CI/CD to run jobs in a pipeline."
executables   = ["gitlab-runner"]

[dotfiles]

# GitLab's official docs say a non-root Unix runner reads ~/.gitlab-runner/
# config.toml; the root/service path is /etc/gitlab-runner and is not a user
# dotfile. The macOS install page confirms the same user path.
# https://docs.gitlab.com/runner/configuration/advanced-configuration/
# https://docs.gitlab.com/runner/install/osx/
paths = ["~/.gitlab-runner/config.toml"]
secret = []

# Registration writes runner authentication tokens and optional S3 cache
# credentials into this TOML file; the official advanced-configuration page
# names all three fields in its register table.
[[dotfiles.secret_paths]]
file = "~/.gitlab-runner/config.toml"
format = "toml"
match = { key_path = ["runners.*.token", "runners.*.cache.s3.AccessKey", "runners.*.cache.s3.SecretKey"] }

[commands]
format = 1
label = "GitLab Runner"
description = "Run the runner, register it with a GitLab instance, or verify registered runners. Service management, run-single, executor-specific registration options and token reset are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = true, short_bundles = false }

[[commands.subcommand]]
path = ["run"]
label = "Run the runner"
description = "Fetch and process jobs from GitLab until stopped."

[[commands.subcommand.source]]
id = "docs"
kind = "manual"
url = "https://docs.gitlab.com/runner/commands/"
revision = "2026-10-27"
evidence = """
gitlab-runner run [command options] [arguments...]
--config  See configuration-file  Specify a custom configuration file to be used
--working-directory  the current directory  Specify the root directory where all data is stored when builds run with the shell executor
--user  the current user  Specify the user that executes builds
--syslog  false  Send all logs to SysLog (Unix) or EventLog (Windows)
--listen-address  empty  Address (<host>:<port>) on which the Prometheus metrics HTTP server should be listening
"""

[[commands.subcommand.field]]
id = "config"
label = "Config file"
type = "path"
option = ["--config"]
path = { kind = "file", role = "input", must_exist = true }
sources = ["docs"]

[[commands.subcommand.field]]
id = "working_directory"
label = "Working directory"
type = "path"
option = ["--working-directory"]
path = { kind = "directory", role = "input", must_exist = false }
sources = ["docs"]

[[commands.subcommand.field]]
id = "user"
label = "Run builds as user"
type = "string"
option = ["--user"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "listen_address"
label = "Metrics listen address"
description = "host:port for the Prometheus metrics server."
type = "string"
option = ["--listen-address"]
sources = ["docs"]

[[commands.subcommand.task]]
id = "run"
label = "Run"
fields = ["config", "working_directory"]
required = []

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["config", "working_directory", "user", "listen_address"]

[[commands.subcommand]]
path = ["register"]
label = "Register a runner"
description = "Register a runner non-interactively with a URL and authentication token."

[[commands.subcommand.source]]
id = "docs"
kind = "manual"
url = "https://docs.gitlab.com/runner/commands/"
revision = "2026-10-27"
evidence = """
gitlab-runner register --name my-runner --url "http://gitlab.example.com" --token my-authentication-token
gitlab-runner register --non-interactive <other-arguments>
--config  See the configuration file section  Specify a custom configuration file to be used
"""

[[commands.subcommand.field]]
id = "url"
label = "GitLab URL"
type = "url"
option = ["--url"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "token"
label = "Authentication token"
type = "string"
option = ["--token"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "name"
label = "Runner name"
type = "string"
option = ["--name"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "non_interactive"
label = "Non-interactive"
type = "boolean"
option = ["--non-interactive"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "config"
label = "Config file"
type = "path"
option = ["--config"]
path = { kind = "file", role = "output", must_exist = false }
effect = "overwrite"
sources = ["docs"]

[[commands.subcommand.task]]
id = "register"
label = "Register"
fields = ["url", "token", "name", "non_interactive"]
required = ["url", "token"]

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["url", "token", "name", "non_interactive", "config"]

[[commands.subcommand]]
path = ["verify"]
label = "Verify runners"
description = "Check that registered runners can connect to GitLab."

[[commands.subcommand.source]]
id = "docs"
kind = "manual"
url = "https://docs.gitlab.com/runner/commands/"
revision = "2026-10-27"
evidence = """
gitlab-runner verify --url "https://gitlab.example.com" --token my-authentication-token
gitlab-runner verify --delete
--config  See the configuration file section  Specify a custom configuration file to be used
"""

[[commands.subcommand.field]]
id = "url"
label = "GitLab URL"
type = "url"
option = ["--url"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "token"
label = "Runner token"
type = "string"
option = ["--token"]
sources = ["docs"]

[[commands.subcommand.field]]
id = "delete"
label = "Delete runners that fail verification"
type = "boolean"
option = ["--delete"]
effect = "delete"
sources = ["docs"]

[[commands.subcommand.field]]
id = "config"
label = "Config file"
type = "path"
option = ["--config"]
path = { kind = "file", role = "input", must_exist = true }
sources = ["docs"]

[[commands.subcommand.task]]
id = "verify"
label = "Verify all"
fields = ["config"]
required = []

[[commands.subcommand.group]]
id = "basic"
label = "Basic"
fields = ["url", "token", "config", "delete"]