This document is for owners and maintainers of Bazel rule repositories. It describes how to configure the Bazel Continuous Integration (CI) system for your repository to test your rules for compatibility against a remote execution scenario. The instructions in this document apply to projects stored in GitHub repositories.
Before completing the steps in this document, ensure the following:
.bazelci/presubmit.yml file, do the following:
a. Add a config named
b. In the
rbe_ubuntu1604 config, add the build and test targets you want to test against remote execution.
Send a pull request with your changes to the
presubmit.yml file. (See
example pull request.)
To view build results, click Details for the RBE (Ubuntu 16.04) pull request check in GItHub, as shown in the figure below. This link becomes available after the pull request has been merged and the CI tests have run. (See example results.)
(Optional) Set the bazel test (RBE (Ubuntu 16.04)) check as a test required to pass before merging in your branch protection rule. The setting is located in GitHub in Settings > Branches > Branch protection rules, as shown in the following figure.
If your build or tests fail, it's likely due to the following:
Required build or test tools are not installed in the default container.
Builds using the
rbe_ubuntu1604 config run by default inside an
container, which includes tools common to many Bazel builds. However, if
your rules require tools not present in the default container, you must
create a custom container based on the
container and include those tools as described later in this document.
Build or test targets are using rules that are incompatible with remote execution. See Adapting Bazel Rules for Remote Execution for details about compatibility wtih remote execution.
rbe-ubuntu16-04 container is publicly available at the following URL:
You can pull it directly from Container Registry or build it from source. The next sections describe both options.
Before you begin, make sure you have installed
If you are building the container from source, you must also install the latest
version of Bazel.
rbe-ubuntu16-04from Container Registry
To pull the Pull the
from Container Registry, run the following command:
gcloud docker -- pull gcr.io/cloud-marketplace/google/rbe-ubuntu16-04@sha256:<sha256-checksum>
<sha256-checksum> with the SHA256 checksum value for
the latest container.
rbe-ubuntu16-04container from source
To build the
rbe-ubuntu16-04 container from source, do the following:
git clone https://github.com/bazelbuild/bazel-toolchains
Set up toolchain container targets and build the container as explained in Toolchain Containers.
Pull the freshly built container:
gcloud docker -- pull gcr.io/<project-id>/<custom-container-name>@sha256:<sha256-checksum>
To run the custom container, do one of the following:
If you pulled the container from Container Registry, run the following command:
docker run -it gcr.io/cloud-marketplace/google/rbe-ubuntu16-04@sha256:<sha256-checksum> /bin/bash
sha256-checksum with the SHA256 checksum value for the
If you built the container from source, run the following command:
docker run -it gcr.io/<project-id>/<custom-container-name>@sha256:<sha256sum> /bin/bash
For example, the following
Dockerfile snippet installs
FROM gcr.io/cloud-marketplace/google/rbe-ubuntu16-04@sha256:<sha256-checksum> RUN apt-get update && yes | apt-get install -y <my_tool_package>
Once you have customized the container, build the container image and push it to Container Registry as follows:
Build the container image:
docker build -t <custom-container-name> .docker tag <custom-container-name> gcr.io/<project-id>/<custom-container-name>
Push the container image to Container Registry:
gcloud docker -- push gcr.io/<project-id>/<custom-container-name>
Navigate to the following URL to verify the container has been pushed:
Take note of the SHA256 checksum of your custom container. You will need to provide it in your build platform definition later in this document.
Configure the container for public access as described in publicly accessible as explained in Serving images publicly.
For more information, see Pushing and Pulling Images.
You must include a
configuration in your custom toolchain configuration, which allows Bazel to
select a toolchain appropriate to the desired hardware/software platform. See
this example platform configuration
for the TensorFlow
Create a similar configuration (that is, using the same constraints) but replace
the value of the
container-image property with the name of your custom
container, as well as your GCR project ID and container image checksum. For
Once you have created a
BUILD file with the platform rule, place it within
your project tree. For example,
Add the appropriate
test_flag entries to the
.bazelci/presubmit.yml file in your
rbe_ubuntu1604config to switch your
builds to using your custom container.
Note: The example linked above uses a platform definition from the
@bazel_toolchains repo. If your platform rule is in
entries would look as follows:
"--extra_execution_platforms=//platforms:<your_platform_target>" "--host_platform=//platforms:<your_platform_target>" "--platforms=//platforms:<your_platform_target>"