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 against a Gitea instance and writes the registration file. Interactive unless --no-interactive is given; the token can also come from --token-file or the GITEA_RUNNER_REGISTRATION_TOKEN environment variable. See Registering a runner.

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)
      --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")
      --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

generate-config

Prints the commented example configuration on stdout, which is the starting point for a config file: gitea-runner generate-config > config.yaml.

Print the example config, which documents every option

Usage:
  gitea-runner generate-config [flags]

Flags:
  -h, --help   help for generate-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

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