Update the runner reference pages (#642)

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-642.docs-gitea-com.pages.dev

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

runner-docs/reference/config-example.md

@@ -57,6 +57,12 @@ runner:
   # PEM client certificate and key for a Gitea instance that requires mutual TLS.
   #client_cert_file: /etc/gitea-runner/client.crt
   #client_key_file: /etc/gitea-runner/client.key
+  # PEM CA certificates of a Gitea instance with a private CA, trusted besides the system's.
+  # Runner-side git and builtin:checkout use it instead of the system's bundle for the instance.
+  # Jobs get it at /var/run/act/ca.crt, or in their act directory on the host, with NODE_EXTRA_CA_CERTS
+  # pointing there unless the job, or on Docker its image, sets it. Other tools in jobs, such as the
+  # git that actions/checkout runs, need the CA in the image's bundle, for example via container.volumes.
+  #ca_file: /etc/gitea-runner/ca.crt
   # The timeout for fetching the job from the Gitea instance.
   # Values above the 60s RPC timeout are capped to it.
   #fetch_timeout: 5s
@@ -126,6 +132,7 @@ runner:
   # If it's empty when execute `daemon`, will use labels in `.runner` file.
   #labels:
   #  - "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest"
+  #  - "ubuntu-26.04:docker://docker.gitea.com/runner-images:ubuntu-26.04"
   #  - "ubuntu-24.04:docker://docker.gitea.com/runner-images:ubuntu-24.04"
   #  - "ubuntu-22.04:docker://docker.gitea.com/runner-images:ubuntu-22.04"
   # Allocate a pseudo-TTY for each step's process. Applies to both host and docker backends.
@@ -219,8 +226,8 @@ cache:
   # How the cache server discards entries, ignored when external_server or s3 is set since
   # those apply their own. Leave a setting out for its default; 0s or 0 turns the three
   # limits off. Sizes accept 10GB, 512mb, 1TiB or a plain byte count, binary either way.
-  # Whatever these allow, the cache still sheds entries to keep free space on its volume
-  # above health_check.min_free_disk_space_mb when health checks are enabled.
+  # Whatever these allow, the cache still sheds entries to keep free space on its volume, room
+  # for uploads included, above health_check.min_free_disk_space_mb when health checks are enabled.
   # Remove entries nothing has read or written within this window. Only last access counts.
   #retention: 168h
   # Cap one repository, removing its least recently accessed entries until it fits. An entry
@@ -277,6 +284,15 @@ container:
   # valid_volumes:
   #   - '**'
   #valid_volumes: []
+  # Volumes and bind mounts the runner adds to every job, service and docker action container, as in
+  # `docker run --volume`, with sources on the docker daemon's host. One the workflow mounts on the same
+  # container path takes its place. Their sources need no valid_volumes entry, and workflow volumes may
+  # use them only with the same access, though a job given the docker socket can mount anything.
+  # Docker only, use pod_template on Kubernetes. For example, to trust a private CA in Debian and
+  # Ubuntu based images:
+  # volumes:
+  #   - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro
+  #volumes: []
   # Overrides the docker client host with the specified one.
   # If it's empty, runner will find an available docker host automatically.
   # If it's "-", runner will find an available docker host automatically, but won't mount it into the job and action containers.
@@ -304,8 +320,8 @@ container:
   # healthy. A negative value (e.g. -1s) starts the steps without waiting.
   #service_ready_timeout: 5m
   # Remove the containers, networks and volumes a job creates through its Docker proxy when
-  # the job ends. Set to false when jobs deploy services to the runner's Docker daemon.
-  #sweep: true
+  # the job ends. Leave off when jobs deploy services to the runner's Docker daemon.
+  #sweep: false
 
 host:
   # The parent directory of a job's working directory.
@@ -340,8 +356,8 @@ health_check:
   # Minimum free space required on the filesystem holding runner workspaces.
   # Defaults to 1024 MiB when omitted or set to zero.
   #min_free_disk_space_mb: 1024
-  # Optional additional executable. A non-zero exit, timeout, or startup failure
-  # marks the runner unavailable.
+  # Optional additional executable, or a .bat or .cmd file on Windows. A non-zero
+  # exit, timeout, or startup failure marks the runner unavailable.
   #script: ''
   # How long a script result is cached and its maximum execution time.
   #interval: 30s

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

@@ -20,13 +20,13 @@ Usage:
   gitea-runner [command]
 
 Available Commands:
-  bug-report      Print information useful when filing a bug report
-  cache-server    Start a cache server for the cache action
-  config          Generate, read and edit config files
-  daemon          Run as a runner daemon
-  exec            Run workflow locally.
-  help            Help about any command
-  register        Register a runner to the server
+  bug-report          Print information useful when filing a bug report
+  cache-server        Start a cache server for the cache action
+  config              Generate, read and edit config files
+  daemon              Run as a runner daemon
+  exec                Run workflow locally.
+  help                Help about any command
+  register            Register a runner to the server
 
 Flags:
   -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable

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

@@ -57,6 +57,12 @@ runner:
   # PEM client certificate and key for a Gitea instance that requires mutual TLS.
   #client_cert_file: /etc/gitea-runner/client.crt
   #client_key_file: /etc/gitea-runner/client.key
+  # PEM CA certificates of a Gitea instance with a private CA, trusted besides the system's.
+  # Runner-side git and builtin:checkout use it instead of the system's bundle for the instance.
+  # Jobs get it at /var/run/act/ca.crt, or in their act directory on the host, with NODE_EXTRA_CA_CERTS
+  # pointing there unless the job, or on Docker its image, sets it. Other tools in jobs, such as the
+  # git that actions/checkout runs, need the CA in the image's bundle, for example via container.volumes.
+  #ca_file: /etc/gitea-runner/ca.crt
   # The timeout for fetching the job from the Gitea instance.
   # Values above the 60s RPC timeout are capped to it.
   #fetch_timeout: 5s
@@ -219,8 +225,8 @@ cache:
   # How the cache server discards entries, ignored when external_server or s3 is set since
   # those apply their own. Leave a setting out for its default; 0s or 0 turns the three
   # limits off. Sizes accept 10GB, 512mb, 1TiB or a plain byte count, binary either way.
-  # Whatever these allow, the cache still sheds entries to keep free space on its volume
-  # above health_check.min_free_disk_space_mb when health checks are enabled.
+  # Whatever these allow, the cache still sheds entries to keep free space on its volume, room
+  # for uploads included, above health_check.min_free_disk_space_mb when health checks are enabled.
   # Remove entries nothing has read or written within this window. Only last access counts.
   #retention: 168h
   # Cap one repository, removing its least recently accessed entries until it fits. An entry
@@ -277,6 +283,15 @@ container:
   # valid_volumes:
   #   - '**'
   #valid_volumes: []
+  # Volumes and bind mounts the runner adds to every job, service and docker action container, as in
+  # `docker run --volume`, with sources on the docker daemon's host. One the workflow mounts on the same
+  # container path takes its place. Their sources need no valid_volumes entry, and workflow volumes may
+  # use them only with the same access, though a job given the docker socket can mount anything.
+  # Docker only, use pod_template on Kubernetes. For example, to trust a private CA in Debian and
+  # Ubuntu based images:
+  # volumes:
+  #   - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro
+  #volumes: []
   # Overrides the docker client host with the specified one.
   # If it's empty, runner will find an available docker host automatically.
   # If it's "-", runner will find an available docker host automatically, but won't mount it into the job and action containers.
@@ -304,8 +319,8 @@ container:
   # healthy. A negative value (e.g. -1s) starts the steps without waiting.
   #service_ready_timeout: 5m
   # Remove the containers, networks and volumes a job creates through its Docker proxy when
-  # the job ends. Set to false when jobs deploy services to the runner's Docker daemon.
-  #sweep: true
+  # the job ends. Leave off when jobs deploy services to the runner's Docker daemon.
+  #sweep: false
 
 host:
   # The parent directory of a job's working directory.
@@ -319,6 +334,18 @@ kubernetes:
   #pod_template: {}
   # Pod templates merged over pod_template, in runs-on order, for jobs whose runs-on has the label they are keyed by.
   #pod_templates: {}
+  # Have job pods fetch directories, such as actions, and copies of 64 KiB or more gzipped from the runner over the pod network,
+  # instead of the runner streaming them through the API server. An init container copies gitea-runner from image into each job pod.
+  # api: through the API server (default). auto: over the pod network, through the API server for a job pod that
+  # cannot reach the runner. direct: over the pod network only, so a broken setup fails jobs instead of quietly
+  # costing API server traffic again.
+  #transfer:
+  #  mode: api
+  #  # Address and port the runner listens on and job pods reach it at, the outbound IP and a free port when empty.
+  #  host: ""
+  #  port: 0
+  #  # Image with gitea-runner on its PATH, the runner pod's image when it has a single container and runs in namespace.
+  #  image: ""
 
 # Optional local task-admission checks. Disabled by default. When enabled, low
 # disk space or a failing script pauses new task fetching; existing jobs continue.
@@ -328,8 +355,8 @@ health_check:
   # Minimum free space required on the filesystem holding runner workspaces.
   # Defaults to 1024 MiB when omitted or set to zero.
   #min_free_disk_space_mb: 1024
-  # Optional additional executable. A non-zero exit, timeout, or startup failure
-  # marks the runner unavailable.
+  # Optional additional executable, or a .bat or .cmd file on Windows. A non-zero
+  # exit, timeout, or startup failure marks the runner unavailable.
   #script: ''
   # How long a script result is cached and its maximum execution time.
   #interval: 30s