act_runner/internal/pkg/config/config.example.yaml

# Example configuration file, it's safe to copy this as the default config file without any modification.

# You don't have to copy this file to your instance,
# just run `./gitea-runner generate-config > config.yaml` to generate a config file.

# 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.
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

runner:
  # Where to store the registration result.
  file: .runner
  # Execute how many tasks concurrently at the same time.
  capacity: 1
  # Extra environment variables to run jobs.
  envs:
    A_TEST_ENV_NAME_1: a_test_env_value_1
    A_TEST_ENV_NAME_2: a_test_env_value_2
  # Extra environment variables to run jobs from a file.
  # It will be ignored if it's empty or the file doesn't exist.
  env_file: .env
  # The timeout for a job to be finished.
  # Please note that the Gitea instance also has a timeout (3h by default) for the job.
  # So the job could be stopped by the Gitea instance if its timeout is shorter than this.
  timeout: 3h
  # The timeout for the runner to wait for running jobs to finish when shutting down.
  # Any running jobs that haven't finished after this timeout will be cancelled.
  shutdown_timeout: 0s
  # Whether skip verifying the TLS certificate of the Gitea instance.
  insecure: false
  # The timeout for fetching the job from the Gitea instance.
  fetch_timeout: 5s
  # The interval for fetching the job from the Gitea instance.
  fetch_interval: 2s
  # The maximum interval for fetching the job from the Gitea instance.
  # The runner uses exponential backoff when idle, increasing the interval up to this maximum.
  # Set to 0 or same as fetch_interval to disable backoff.
  fetch_interval_max: 5s
  # While idle, remove stale bind-workdir task directories older than this duration.
  # Setting either workdir_cleanup_age or idle_cleanup_interval to 0 (or any
  # non-positive value) disables workdir cleanup entirely.
  workdir_cleanup_age: 24h
  # Cadence for the idle stale bind-workdir cleanup pass.
  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
  # or if log_report_max_latency expires after the first buffered row.
  log_report_interval: 5s
  # The maximum time a log row can wait before being sent.
  # This ensures even a single log line appears on the frontend within this duration.
  # Must be less than log_report_interval to have any effect.
  log_report_max_latency: 3s
  # Flush logs immediately when the buffer reaches this many rows.
  # This ensures bursty output (e.g., npm install) is delivered promptly.
  log_report_batch_size: 100
  # The interval for reporting task state (step status, timing) to the Gitea instance.
  # State is also reported immediately on step transitions (start/stop).
  state_report_interval: 5s
  # The github_mirror of a runner is used to specify the mirror address of the github that pulls the action repository.
  # It works when something like `uses: actions/checkout@v4` is used and DEFAULT_ACTIONS_URL is set to github,
  # and github_mirror is not empty. In this case,
  # it replaces https://github.com with the value here, which is useful for some special network environments.
  github_mirror: ''
  # 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 .
  # If it's empty when registering, it will ask for inputting labels.
  # 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-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.
  # Default false matches GitHub actions/runner. Enable only for jobs that need an interactive
  # terminal; tools like `docker build` emit redrawing progress frames into the captured log
  # when a TTY is present.
  allocate_pty: false

cache:
  # Enable cache server to use actions/cache.
  enabled: true
  # The directory to store the cache data.
  # If it's empty, the cache data will be stored in $HOME/.cache/actcache.
  dir: ""
  # The host of the cache server.
  # It's not for the address to listen, but the address to connect from job containers.
  # So 0.0.0.0 is a bad choice, leave it empty to detect automatically.
  host: ""
  # The port of the cache server.
  # 0 means to use a random available port.
  port: 0
  # The external cache server URL. Valid only when enable is true.
  # If it's specified, runner will use this URL as the ACTIONS_CACHE_URL rather than start a server by itself.
  # The URL should generally end with "/".
  # Requires external_secret below to be set to the same value on both this runner and the cache-server.
  external_server: ""
  # Shared secret between this runner and the external `gitea-runner cache-server`. Required when external_server
  # (or `gitea-runner cache-server`) is in use: the runner pre-registers each job's ACTIONS_RUNTIME_TOKEN with the
  # cache-server, and the cache-server enforces bearer auth + per-repo cache isolation.
  external_secret: ""

container:
  # Specifies the network to which the container will connect.
  # Could be host, bridge or the name of a custom network.
  # If it's empty, runner will create a network automatically.
  # Deprecated: `network_mode` is still accepted for old configs; use `network` instead.
  network: ""
  # Whether to use privileged mode or not when launching task containers (privileged mode is required for Docker-in-Docker).
  privileged: false
  # Any other options to be used when the container is started (e.g., --add-host=my.gitea.url:host-gateway).
  options:
  # The parent directory of a job's working directory.
  # NOTE: There is no need to add the first '/' of the path as runner will add it automatically.
  # If the path starts with '/', the '/' will be trimmed.
  # For example, if the parent directory is /path/to/my/dir, workdir_parent should be path/to/my/dir
  # If it's empty, /workspace will be used.
  # Purely numeric subdirectories under this path are reserved for task workspaces and may be removed by idle cleanup.
  workdir_parent:
  # Volumes (including bind mounts) can be mounted to containers. Glob syntax is supported, see https://github.com/gobwas/glob
  # You can specify multiple volumes. If the sequence is empty, no volumes can be mounted.
  # For example, if you only allow containers to mount the `data` volume and all the json files in `/src`, you should change the config to:
  # valid_volumes:
  #   - data
  #   - /src/*.json
  # If you want to allow any volume, please use the following configuration:
  # valid_volumes:
  #   - '**'
  valid_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 the docker host won't be mounted to the job containers and service containers.
  # If it's not empty or "-", the specified docker host will be used. An error will be returned if it doesn't work.
  docker_host: ""
  # Pull docker image(s) even if already present
  force_pull: true
  # Rebuild docker image(s) even if already present
  force_rebuild: false
  # Always require a reachable docker daemon, even if not required by runner
  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.
  # This is required for Docker-in-Docker (DinD) setups when jobs use docker compose
  # with bind mounts (e.g., ".:/app"), as volume-based workspaces are not accessible
  # from the DinD daemon's filesystem. When enabled, ensure the workspace parent
  # directory is also mounted into the runner container and listed in valid_volumes.
  bind_workdir: false

host:
  # The parent directory of a job's working directory.
  # If it's empty, $HOME/.cache/act/ will be used.
  workdir_parent:

metrics:
  # Enable the Prometheus metrics endpoint.
  # When enabled, metrics are served at http://<addr>/metrics and a liveness check at /healthz.
  enabled: false
  # The address for the metrics HTTP server to listen on.
  # Defaults to localhost only. Set to ":9101" to allow external access,
  # but ensure the port is firewall-protected as there is no authentication.
  addr: "127.0.0.1:9101"