Version 1.49 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://

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

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: "False"

Enables reuse of Docker containers without shutting them down. This significantly reduces the overhead of container startup on action execution at the cost of an increased risk of cross-action contamination. We recommend disabling this feature for release builds. If reuse is disabled on the server, then this option is silently ignored.

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.

Machine platform

Pool: "null"

The pool name of the worker.

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.

experimentalActionInputStrategy: "auto"

Setting to determine how action inputs are presented on the local file system. This can be one of 'hardlink', 'symlink', 'copy', or 'clonefile' (only if the worker is running on MacOS).

Each worker has a local content-addressable store into which it fetches all required inputs before executing an action. It then creates an action input tree on the file system by either hardlinking, copying, symlinking, or cloning requested files from the local CAS.

Hardlinking and symlinking are typically faster than copying as no file contents have to be transferred. However, the files will have the same mod bits as the files stored in the CAS - for maximum compatibility, these are readable and executable (not writable).

An additional drawback of the 'symlink' strategy is that dynamic libraries may not be loaded correctly, i.e., the dynamic linker may be unable to find a dynamic library that is linked using a relative path. Either use this only for actions that don't need dynamically linked binaries, or set LD_LIBRARY_PATH appropriately to override the linker search path.

Copying is the slowest option, but sets the executable bit according to the client request (note that input files are still not writeable).

Cloning is available on MacOS (High Sierra or later) and Linux (only on some file systems: bcachefs, btrfs, xfs, ocfs2): it has similar performance as hardlinking, but also allows setting different mod bits like copying. On MacOS, it additionally avoids issues with the MacOS Gatekeeper feature that can be confused by hardlinks and incorrectly terminate actions.

We recommend to leave this at the default 'auto' setting which uses 'clonefile' on MacOS, and 'hardlink' on Linux.

On Linux, use 'copy' or 'clonefile' if you require mod bits to be accurate, e.g., for packaging, or 'symlink' if you have configured the workers to use an in-memory file system.

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 except localhost, and to 'standard' to allow network connections.

sandboxUserId: "self"

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

Last modified 2021-08-05