Update the runner reference pages (#547)

Automated update of the generated runner reference pages from gitea/runner (main for the develop docs, the newest stable tag for every documented series), opened by the "update runner reference" scheduled workflow.

<!-- cloudflare-preview --> Preview: https://pr-547.docs-gitea-com.pages.dev

Reviewed-on: https://gitea.com/gitea/docs/pulls/547
Reviewed-by: silverwind <[email protected]>
Co-authored-by: Gitea Bot <[email protected]>

runner-docs/reference/config-example.md

@@ -68,11 +68,12 @@ runner:
   # scratch directories (left behind when a host cleanup delete stalls) older than
   # this duration. Setting either workdir_cleanup_age or idle_cleanup_interval to 0
   # (or any non-positive value) disables stale-directory cleanup entirely, along with
-  # the docker network cleanup below.
+  # the docker network and volume cleanup below.
   #workdir_cleanup_age: 24h
   # Cadence for the idle cleanup pass. Besides the directories above, on runners that use
-  # docker it removes the per-job networks of jobs this runner did not live to tear down,
+  # docker it removes the per-job networks and volumes of jobs this runner did not live to
-  # which would otherwise hold a subnet of the daemon address pool until the host is rebuilt.
+  # tear down, which would otherwise hold a subnet of the daemon address pool and the job's
+  # workspace contents until the host is rebuilt.
   #idle_cleanup_interval: 10m
   # The base interval for periodic log flush to the Gitea instance.
   # Logs may be sent earlier if the buffer reaches log_report_batch_size
@@ -154,7 +155,8 @@ runner:
   #  job_completed: ''
 
 cache:
-  # Enable the built-in cache server (used by actions/cache and similar actions).
+  # Enable caching (used by actions/cache and similar actions). Off means no built-in server is
+  # started and no job is registered with an external_server either.
   #enabled: true
   # Directory where cache blobs are stored on disk. Default: $HOME/.cache/actcache
   # Ignored when external_server is set.
@@ -191,9 +193,9 @@ cache:
   # until its cache entry expires or is manually removed.
   #offline_mode: false
   # Serve the actions cache service v2 API. The actions that use it refuse any host they do not
-  # take for GitHub, so reaching it means editing that check out of their own bundle, undone
+  # take for GitHub, so reaching it means editing that check out of their own bundle, put back
-  # whenever it is downloaded again. That edit is made either way, this only governs the API
+  # after the copy into the job. That edit is made either way, this only governs the API
-  # advertised. A bundle that does not match is left alone.
+  # advertised. A bundle that does not match is left alone. With v2, uploads need a reachable cache.
   #v2: true
   # How the cache server discards entries, ignored when external_server is set since that
   # server applies its own. Leave a setting out for its default; 0s or 0 turns the three
@@ -271,11 +273,10 @@ container:
   #require_docker: false
   # Timeout to wait for the docker daemon to be reachable, if docker is required by require_docker or runner
   #docker_timeout: 0s
-  # Bind the workspace to the host filesystem instead of using Docker volumes.
+  # Mount the workspace from a host directory instead of a Docker volume, so jobs
-  # This is required for Docker-in-Docker (DinD) setups when jobs use docker compose
+  # can bind-mount it by its own path into sibling containers (".:/app" in docker
-  # with bind mounts (e.g., ".:/app"), as volume-based workspaces are not accessible
+  # compose). Not needed when workflows use the GITEA_DOCKER_WORKSPACE variable.
-  # from the DinD daemon's filesystem. When enabled, ensure the workspace parent
+  # The workspace parent directory must be mounted into the runner container.
-  # directory is also mounted into the runner container and listed in valid_volumes.
   #bind_workdir: false
   # How long a job waits for a service container that declares a healthcheck to become
   # healthy. A negative value (e.g. -1s) starts the steps without waiting.

runner-docs_versioned_docs/version-3/reference/cli.md

@@ -103,13 +103,15 @@ Flags:
       --detect-event                     Use first event type from workflow as event that triggered the workflow
   -C, --directory string                 working directory (default ".")
   -n, --dryrun                           dryrun mode
-      --env stringArray                  env to make available to actions with optional value (e.g. --env myenv=foo or --env myenv)
+      --env stringArray                  env to make available to actions with optional value (e.g. --env myenv=foo or --env myenv; override env-file)
       --env-file string                  environment file to read and use as env in the containers (default ".env")
   -E, --event string                     run a event name
   -e, --eventpath string                 path to a JSON event payload file exposed as the event that triggered the workflow
       --gitea-instance string            Gitea instance to use.
   -h, --help                             help for exec
   -i, --image string                     Docker image to use. Use "-self-hosted" to run directly on the host. (default "docker.gitea.com/runner-images:ubuntu-latest")
+      --input stringArray                set an input the workflow declares under its workflow_dispatch or workflow_call trigger, others stay invisible to the inputs context (e.g. --input name=bar; can be specified multiple times with highest precedence)
+      --input-file string                path to an .env-format file containing key=value pairs as baseline workflow inputs (override event inputs)
       --insecure-secrets                 NOT RECOMMENDED! Doesn't hide secrets while printing logs.
   -j, --job string                       run a specific job ID; when several workflow files define that job, also pass --workflows/-W to select the file
       --json                             Output logs in json format

runner-docs_versioned_docs/version-3/reference/config-example.md

@@ -154,7 +154,8 @@ runner:
   #  job_completed: ''
 
 cache:
-  # Enable the built-in cache server (used by actions/cache and similar actions).
+  # Enable caching (used by actions/cache and similar actions). Off means no built-in server is
+  # started and no job is registered with an external_server either.
   #enabled: true
   # Directory where cache blobs are stored on disk. Default: $HOME/.cache/actcache
   # Ignored when external_server is set.
@@ -191,9 +192,9 @@ cache:
   # until its cache entry expires or is manually removed.
   #offline_mode: false
   # Serve the actions cache service v2 API. The actions that use it refuse any host they do not
-  # take for GitHub, so reaching it means editing that check out of their own bundle, undone
+  # take for GitHub, so reaching it means editing that check out of their own bundle, put back
-  # whenever it is downloaded again. That edit is made either way, this only governs the API
+  # after the copy into the job. That edit is made either way, this only governs the API
-  # advertised. A bundle that does not match is left alone.
+  # advertised. A bundle that does not match is left alone. With v2, uploads need a reachable cache.
   #v2: true
   # How the cache server discards entries, ignored when external_server is set since that
   # server applies its own. Leave a setting out for its default; 0s or 0 turns the three
@@ -271,11 +272,10 @@ container:
   #require_docker: false
   # Timeout to wait for the docker daemon to be reachable, if docker is required by require_docker or runner
   #docker_timeout: 0s
-  # Bind the workspace to the host filesystem instead of using Docker volumes.
+  # Mount the workspace from a host directory instead of a Docker volume, so jobs
-  # This is required for Docker-in-Docker (DinD) setups when jobs use docker compose
+  # can bind-mount it by its own path into sibling containers (".:/app" in docker
-  # with bind mounts (e.g., ".:/app"), as volume-based workspaces are not accessible
+  # compose). Not needed when workflows use the GITEA_DOCKER_WORKSPACE variable.
-  # from the DinD daemon's filesystem. When enabled, ensure the workspace parent
+  # The workspace parent directory must be mounted into the runner container.
-  # directory is also mounted into the runner container and listed in valid_volumes.
   #bind_workdir: false
   # How long a job waits for a service container that declares a healthcheck to become
   # healthy. A negative value (e.g. -1s) starts the steps without waiting.