diff --git a/runner-docs/reference/cli.md b/runner-docs/reference/cli.md index 0fdba377..553196b9 100644 --- a/runner-docs/reference/cli.md +++ b/runner-docs/reference/cli.md @@ -121,6 +121,7 @@ Flags: -p, --pull pull docker image(s) even if already present --rebuild rebuild local action docker image(s) even if already present -s, --secret stringArray secret to make available to actions with optional value (e.g. -s mysecret=foo or -s mysecret) + --tool-cache-mode string What to mount at RUNNER_TOOL_CACHE: none, or shared to reuse one tool cache across runs (default "none") --use-gitignore Controls whether paths specified in .gitignore should be copied into container (default true) --userns string user namespace to use --var stringArray variable to make available to actions with optional value (e.g. --var myvar=foo or --var myvar) diff --git a/runner-docs/reference/config-example.md b/runner-docs/reference/config-example.md index 78ff6edd..060ec25a 100644 --- a/runner-docs/reference/config-example.md +++ b/runner-docs/reference/config-example.md @@ -16,13 +16,20 @@ loaded. # Every option with its default value, all commented out. Read this file, do not copy it. # `./gitea-runner config init` writes a config file to copy the lines you change into. -# Logging for the runner process itself (messages printed to stderr). -# This does not control how workflow step output is streamed to the Gitea UI; -# tune that with runner.log_report_* below. +# Logging for the runner process itself (messages printed to stderr), plus the copy of +# each task's log kept under log.job. Neither controls how workflow step output is streamed +# to the Gitea UI; tune that with runner.log_report_* below. log: # logrus severity: trace, debug, info, warn, error, fatal, panic. # trace and debug turn on caller/file:line in log lines. Default if omitted: info. #level: info + # Write a copy of each task's log to dir as -task-.log, so a job's output + # survives a failure to send it to Gitea. A path turns them on, empty turns them off. + # retention is how long a log is kept (0s keeps all), max_size caps one log (0 is no limit). + #job: + # dir: "" + # retention: 168h + # max_size: 1GB runner: # Where to store the registration result. @@ -49,6 +56,7 @@ runner: # Whether skip verifying the TLS certificate of the Gitea instance. #insecure: false # The timeout for fetching the job from the Gitea instance. + # Values above the 60s RPC timeout are capped to it. #fetch_timeout: 5s # The interval for fetching the job from the Gitea instance. #fetch_interval: 2s @@ -94,6 +102,10 @@ runner: # When true (the default), inject the ACT=true environment variable into jobs. # Set to false so workflows gated on `if: ${{ !env.ACT }}` behave like they do on GitHub. #set_act_env: true + # When true (the default), apply compatibility patches to the actions a job runs, so actions + # written for GitHub work against this instance. Set to false to run them exactly as published, + # at the price of the stock artifact actions refusing and the cache client keeping to v1. + #patch_actions: true # The labels of a runner are used to determine which jobs the runner can run, and how to run them. # Like: "macos-arm64:host" or "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest" # Find more images provided by Gitea at https://gitea.com/gitea/runner-images . @@ -108,6 +120,15 @@ runner: # terminal; tools like `docker build` emit redrawing progress frames into the captured log # when a TTY is present. #allocate_pty: false + # Image for a job whose runs-on matches none of the labels above. A runner without a + # docker daemon runs such a job on the host instead. + #default_image: "docker.gitea.com/runner-images:ubuntu-latest" + # What to mount at RUNNER_TOOL_CACHE (/opt/hostedtoolcache), where setup actions install tools: + # none: nothing. A docker job sees what its image ships there, a host job an empty dir, and + # either way what it installs is gone when the job ends. + # shared: one tool cache every job reuses. Two jobs writing the same tool version at once + # corrupt it, so use it only with capacity 1. + #tool_cache_mode: none # Optional executable on the host, run once after each task's built-in cleanup # (post-steps, container teardown, bind-workdir removal). Additive only. # @@ -169,11 +190,25 @@ cache: # A moved tag (e.g. a re-tagged "v6") or an updated branch stays at the cached commit # until its cache entry expires or is manually removed. #offline_mode: false - # Serve the actions cache service v2 API, used by actions/cache@v4.2 and later. Those actions - # refuse any host they do not take for GitHub, so reaching it means editing that check out of - # the action's own bundle, keeping the untouched copy beside it. The same edit lets the stock - # upload-artifact and download-artifact work here. A bundle that does not match is left alone. + # 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 + # whenever it is downloaded again. That edit is made either way, this only governs the API + # advertised. A bundle that does not match is left alone. #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 + # 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. + # 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 + # larger than the limit is dropped rather than emptying the repository to make room. + #repo_size_limit: 10GB + # Cap the whole cache the same way. Off by default, since the free space floor bounds it. + #size_limit: 0 + # Minimum time between two eviction sweeps. This one has no "off". + #sweep_interval: 1h container: # Specifies the network to which the container will connect. @@ -196,7 +231,7 @@ container: #privileged: false # Any other options to be used when the container is started, for example: # options: --add-host=my.gitea.url:host-gateway - # A volume declared here replaces the one the runner mounts on the same container path, so the + # A volume declared here replaces the one the runner would mount on the same container path, so the # tool cache can be kept on the host. Its source must also be allowed by valid_volumes below: # options: --volume /host/toolcache:/opt/hostedtoolcache #options: diff --git a/runner-docs_versioned_docs/version-3/reference/cli.md b/runner-docs_versioned_docs/version-3/reference/cli.md index 0fdba377..553196b9 100644 --- a/runner-docs_versioned_docs/version-3/reference/cli.md +++ b/runner-docs_versioned_docs/version-3/reference/cli.md @@ -121,6 +121,7 @@ Flags: -p, --pull pull docker image(s) even if already present --rebuild rebuild local action docker image(s) even if already present -s, --secret stringArray secret to make available to actions with optional value (e.g. -s mysecret=foo or -s mysecret) + --tool-cache-mode string What to mount at RUNNER_TOOL_CACHE: none, or shared to reuse one tool cache across runs (default "none") --use-gitignore Controls whether paths specified in .gitignore should be copied into container (default true) --userns string user namespace to use --var stringArray variable to make available to actions with optional value (e.g. --var myvar=foo or --var myvar) diff --git a/runner-docs_versioned_docs/version-3/reference/config-example.md b/runner-docs_versioned_docs/version-3/reference/config-example.md index d37bce68..060ec25a 100644 --- a/runner-docs_versioned_docs/version-3/reference/config-example.md +++ b/runner-docs_versioned_docs/version-3/reference/config-example.md @@ -16,13 +16,20 @@ loaded. # Every option with its default value, all commented out. Read this file, do not copy it. # `./gitea-runner config init` writes a config file to copy the lines you change into. -# Logging for the runner process itself (messages printed to stderr). -# This does not control how workflow step output is streamed to the Gitea UI; -# tune that with runner.log_report_* below. +# Logging for the runner process itself (messages printed to stderr), plus the copy of +# each task's log kept under log.job. Neither controls how workflow step output is streamed +# to the Gitea UI; tune that with runner.log_report_* below. log: # logrus severity: trace, debug, info, warn, error, fatal, panic. # trace and debug turn on caller/file:line in log lines. Default if omitted: info. #level: info + # Write a copy of each task's log to dir as -task-.log, so a job's output + # survives a failure to send it to Gitea. A path turns them on, empty turns them off. + # retention is how long a log is kept (0s keeps all), max_size caps one log (0 is no limit). + #job: + # dir: "" + # retention: 168h + # max_size: 1GB runner: # Where to store the registration result. @@ -49,6 +56,7 @@ runner: # Whether skip verifying the TLS certificate of the Gitea instance. #insecure: false # The timeout for fetching the job from the Gitea instance. + # Values above the 60s RPC timeout are capped to it. #fetch_timeout: 5s # The interval for fetching the job from the Gitea instance. #fetch_interval: 2s @@ -94,6 +102,10 @@ runner: # When true (the default), inject the ACT=true environment variable into jobs. # Set to false so workflows gated on `if: ${{ !env.ACT }}` behave like they do on GitHub. #set_act_env: true + # When true (the default), apply compatibility patches to the actions a job runs, so actions + # written for GitHub work against this instance. Set to false to run them exactly as published, + # at the price of the stock artifact actions refusing and the cache client keeping to v1. + #patch_actions: true # The labels of a runner are used to determine which jobs the runner can run, and how to run them. # Like: "macos-arm64:host" or "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest" # Find more images provided by Gitea at https://gitea.com/gitea/runner-images . @@ -108,6 +120,15 @@ runner: # terminal; tools like `docker build` emit redrawing progress frames into the captured log # when a TTY is present. #allocate_pty: false + # Image for a job whose runs-on matches none of the labels above. A runner without a + # docker daemon runs such a job on the host instead. + #default_image: "docker.gitea.com/runner-images:ubuntu-latest" + # What to mount at RUNNER_TOOL_CACHE (/opt/hostedtoolcache), where setup actions install tools: + # none: nothing. A docker job sees what its image ships there, a host job an empty dir, and + # either way what it installs is gone when the job ends. + # shared: one tool cache every job reuses. Two jobs writing the same tool version at once + # corrupt it, so use it only with capacity 1. + #tool_cache_mode: none # Optional executable on the host, run once after each task's built-in cleanup # (post-steps, container teardown, bind-workdir removal). Additive only. # @@ -152,6 +173,7 @@ cache: #port: 0 # URL of a shared `gitea-runner cache-server` to use instead of starting a local one. # Set on every runner that should share a cache pool. A trailing slash is optional. + # Jobs reach the server at this URL too, so set it to the reverse proxy when one fronts the server. # Example: "http://cache-host:8088/" # Requires external_secret (below) to match the value on the cache-server. #external_server: "" @@ -168,11 +190,25 @@ cache: # A moved tag (e.g. a re-tagged "v6") or an updated branch stays at the cached commit # until its cache entry expires or is manually removed. #offline_mode: false - # Serve the actions cache service v2 API, used by actions/cache@v4.2 and later. Those actions - # refuse any host they do not take for GitHub, so reaching it means editing that check out of - # the action's own bundle, keeping the untouched copy beside it. The same edit lets the stock - # upload-artifact and download-artifact work here. A bundle that does not match is left alone. + # 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 + # whenever it is downloaded again. That edit is made either way, this only governs the API + # advertised. A bundle that does not match is left alone. #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 + # 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. + # 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 + # larger than the limit is dropped rather than emptying the repository to make room. + #repo_size_limit: 10GB + # Cap the whole cache the same way. Off by default, since the free space floor bounds it. + #size_limit: 0 + # Minimum time between two eviction sweeps. This one has no "off". + #sweep_interval: 1h container: # Specifies the network to which the container will connect. @@ -195,7 +231,7 @@ container: #privileged: false # Any other options to be used when the container is started, for example: # options: --add-host=my.gitea.url:host-gateway - # A volume declared here replaces the one the runner mounts on the same container path, so the + # A volume declared here replaces the one the runner would mount on the same container path, so the # tool cache can be kept on the host. Its source must also be allowed by valid_volumes below: # options: --volume /host/toolcache:/opt/hostedtoolcache #options: