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

sidebar_position, description

sidebar_position	description
1	Every gitea-runner command and flag, generated from the runner sources.

Command line reference

{/* Generated by update_runner_docs.sh from the gitea/runner sources, do not edit. */}

gitea-runner is a single binary with one subcommand per task. --config / -c is global: every command that reads configuration accepts it, and commands that do not read any ignore it.

gitea-runner

Gitea Runner

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

Flags:
  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable
  -h, --help            help for gitea-runner
  -v, --version         version for gitea-runner

Use "gitea-runner [command] --help" for more information about a command.

register

Registers the runner with a Gitea instance and writes the registration file. The token comes from --token, --token-file or the GITEA_RUNNER_REGISTRATION_TOKEN environment variable, and the command asks for the other settings unless --no-interactive is given. See Registration.

Register a runner to the server

Usage:
  gitea-runner register [flags]

Flags:
      --ephemeral           Configure the runner to be ephemeral and only ever be able to pick a single job (stricter than --once)
  -h, --help                help for register
      --instance string     Gitea instance address
      --labels string       Runner tags, comma separated
      --name string         Runner name
      --no-interactive      Disable interactive mode
      --token string        Runner token (or set the GITEA_RUNNER_REGISTRATION_TOKEN envvar)
      --token-file string   Path to a file containing the runner token

Global Flags:
  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable

daemon

Runs the runner: it polls the instance for jobs and executes them until it is stopped. --labels (default: GITEA_RUNNER_LABELS) overrides the labels of an already registered runner, and --once exits after a single job.

Run as a runner daemon

Usage:
  gitea-runner daemon [flags]

Flags:
  -h, --help            help for daemon
      --labels string   Runner labels, comma separated. Overrides the labels of an already registered runner
      --once            Run one job then exit

Global Flags:
  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable

exec

Runs a workflow from the current repository locally, without a Gitea instance and without the runner configuration file. Useful for debugging a workflow before pushing it. Runner YAML is not loaded, so hooks and cache settings do not apply.

Run workflow locally.

Usage:
  gitea-runner exec [flags]

Flags:
      --artifact-server-addr string      Defines the address where the artifact server listens
      --artifact-server-path string      Defines the path where the artifact server stores uploads and retrieves downloads from. If not specified the artifact server will not start. (default ".")
      --artifact-server-port string      Defines the port where the artifact server listens (will only bind to localhost). (default "34567")
      --container-architecture string    Architecture which should be used to run containers, e.g.: linux/amd64. If not specified, will use host default architecture. Requires Docker server API Version 1.41+. Ignored on earlier Docker server platforms.
      --container-cap-add stringArray    kernel capabilities to add to the workflow containers (e.g. --container-cap-add SYS_PTRACE)
      --container-cap-drop stringArray   kernel capabilities to remove from the workflow containers (e.g. --container-cap-drop SYS_PTRACE)
      --container-daemon-socket string   Path to Docker daemon socket which will be mounted to containers (default "/var/run/docker.sock")
      --container-opts string            container options
  -d, --debug                            enable debug log
      --default-actions-url string       Defines the default url of action instance. (default "https://github.com")
      --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; 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
  -l, --list                             list workflows
      --network string                   Specify the network to which the container will connect
      --no-recurse                       Flag to disable running workflows from subdirectories of specified path in '--workflows'/'-W' flag
      --no-skip-checkout                 Do not skip actions/checkout
      --privileged                       use privileged mode
  -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)
  -W, --workflows string                 path to workflow file(s) (default "./.gitea/workflows/")

Global Flags:
  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable

cache-server

Runs only the cache server, so several runners can share one cache. --dir, --host and --port override the matching cache.* keys. Every other setting, cache.external_secret included, has to come from the config file. See Caching.

Start a cache server for the cache action

Usage:
  gitea-runner cache-server [flags]

Flags:
  -d, --dir string    Cache directory
  -h, --help          help for cache-server
  -s, --host string   Host of the cache server
  -p, --port uint16   Port of the cache server

Global Flags:
  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable

config

Writes, reads and edits config files. config init writes a minimal config.yaml, config set, add and remove change it in place, and config generate prints every option. See Configuration.

Generate, read and edit config files

Usage:
  gitea-runner config [flags]
  gitea-runner config [command]

Available Commands:
  add         Append values to a list config key
  generate    Print the example config, which documents every option
  get         Print the value of a config key
  init        Write a minimal config file
  remove      Remove values from a list config key
  set         Set the value of a config key

Flags:
  -h, --help   help for config

Global Flags:
  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable

Use "gitea-runner config [command] --help" for more information about a command.

config add

Append values to a list config key

Usage:
  gitea-runner config add <key> <value>... [flags]

Flags:
  -h, --help   help for add

Global Flags:
  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable

config generate

Print the example config, which documents every option

Usage:
  gitea-runner config generate [flags]

Flags:
  -h, --help   help for generate

Global Flags:
  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable

config get

Print the value of a config key

Usage:
  gitea-runner config get <key> [flags]

Flags:
  -h, --help   help for get

Global Flags:
  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable

config init

Write a minimal config file, leaving every option at its default.
Without --config it writes config.yaml in the working directory.

Usage:
  gitea-runner config init [flags]

Flags:
  -f, --force   overwrite an existing config file
  -h, --help    help for init

Global Flags:
  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable

config remove

Remove values from a list config key

Usage:
  gitea-runner config remove <key> <value>... [flags]

Flags:
  -h, --help   help for remove

Global Flags:
  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable

config set

Set the value of a config key

Usage:
  gitea-runner config set <key> <value>... [flags]

Flags:
  -h, --help   help for set

Global Flags:
  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable

bug-report

Prints the runner version, Go version, OS/architecture and CPU count, for pasting into an issue.

Print information useful when filing a bug report

Usage:
  gitea-runner bug-report [flags]

Flags:
  -h, --help   help for bug-report

Global Flags:
  -c, --config config   Config file path. config subcommands fall back to config.yaml in the working directory or next to the executable