Version 2.5 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

Platform Options Reference

Description of all command-line options that configure action execution platforms

Docker platform

container-image: "null"

The docker container image URL in which to run the action. This needs to start with the string 'docker://' and should also include a digest, such as docker://gcr.io/engflow/ubuntu-18.04@sha256:123456789abcdef.

The execution server can be configured to restrict whether docker actions are supported at all, which images are allowed, as well as what additional restrictions are placed on the container. For Bazel users, we recommend using the workspace rules provided in the https://github.com/bazelbuild/bazel-toolchains project to configure the docker container.

If this option is unset or set to an empty string, then docker execution is disabled, and the server may fall back to sandboxed or local execution (if enabled) or return an error.

dockerAddCapabilities: "null"

A comma-separated list of additional capabilities that are added to the docker container where this action runs. The capability names must be sorted alphabetically. It is an error to specify empty names, or to specify the same names as for dockerDropCapabilities.

The execution server can be configured to restrict which capabilities it accepts. For more information on the list of supported capabilities, see the documentation of docker run.

dockerDropCapabilities: "null"

A comma-separated list of capabilities that are dropped when running the action in docker. The capability names must be sorted alphabetically. It is an error to specify empty names, or to specify the same names as for dockerAddCapabilities.

For more information on the list of supported capabilities, see the documentation of docker run.

dockerNetwork: "null"

Configures the network that is accessible within the docker container running the action.

Omit or set to the empty string to use the default network mode configured server-side (see --docker_default_network_mode).

Set to off to disable networking except localhost (as seen from the container, i.e. the container itself).

Set to standard to allow network connections to sibling containers and the internet (if the server is configured to allow internet access). The $HOST_NETWORK_NAME environment variable in the action execution container will be set to the docker network name. The action should run sibling containers with --network=$HOST_NETWORK_NAME to let them join the network.

dockerReuse: "True"

Opt-out of Docker containers reuse for individual actions; only has an effect if reuse is enabled in the service. Docker container reuse effectively eliminates the overhead of container startup on action execution at the cost of a slightly increased risk of cross-action contamination.

dockerRunAsRoot: "False"

If this option is disabled, actions are run as 'nobody:nogroup'. If enabled, then the action is instead run as 'root:root'. If the functionality is disabled on the server (see --experimental_docker_use_platform_user), then this option is silently ignored.

dockerRuntime: "null"

Docker runtime to use to run the action. This requires having the corresponding runtime installed on the server.

The execution server can be configured to restrict this ability using --docker_allow_any_runtime and --docker_allowed_runtimes.

dockerSiblingContainers: "False"

Whether to mount the docker socket into the docker container running the action. Doing so allows actions to run docker to spawn sibling containers (i.e., containers running next to the container running the action).

The execution server can be configured to restrict this ability.

dockerUseEntrypoint: "True"

Whether to use the entrypoint specified in the Docker image. If this is set to false, then the entrypoint is overwritten by the server.

engflow:incompatibleRequireCanonicalContainerImage: "False"

Whether container-image must be a canonical URL (i.e. include the digest).

Machine platform

Pool: "null"

The pool name of the worker. Semantics are affected by --incompatible_named_default_pool.

cache-silo-key: "null"

An arbitrary string. Different settings for this option effectively create separate cache silos: clients can only ever receive cache hits from other clients (across users or over time) that have the identical setting.

This can be used to prevent cache hits when switching server default options that affect action execution (e.g., enabling or disabling sandboxing) or between different client configurations when using the service as a remote cache if those client configurations affect the build non-hermetically.

Note that this can increase action cache storage requirements.

Persistent worker platform

persistentWorkerKey: "null"

A cryptographic hash of the names and contents of inputs to the persistent worker process. If you are using persistent workers with Docker containers, you must also enable the dockerReuse option, or the Docker container shutdown implicitly shuts down the persistent worker process. Note that the client must also annotate the corresponding files with the bazel_tool_input setting.

Sandbox platform

sandboxAllowed: "True"

Whether the action can run in a sandbox. Set to 'False' to prevent actions from running in the sandbox. In that case, the server may fallback to local non-sandboxed execution (if enabled), or return an error.

sandboxNetwork: "off"

Configures the network that is accessible within the sandbox running the action. Set to 'off' to disable networking, and to 'standard' to allow network connections (including localhost).

sandboxUserId: "self"

Configures the user id that the action runs as inside the sandbox. Possible values are 'self', 'root', and 'nobody'.

2022-04-28