BuildBuddy Documentation

Buck2 is an artifact-based build tool, similar to Buck(1) and Bazel, that operates on a large graph of dependencies. Rewritten in Rust by Meta, it is designed with the following core principles:

1. Remote Execution first: Built to support distributed execution environments.
2. Dynamic graph computation engine: Capable of handling complex dependency graphs.
3. A single build phase: Streamlines the build process into a unified phase.

Buck2 is compatible with BuildBuddy's Remote Cache and Remote Build Execution (RBE) offerings.

BuildBuddy's Remote Build Execution service includes the following capabilities:

• Custom Docker image support: Use your own container images for build environments.
• Three-tier artifact caching: Optimized caching layers for build outputs.
• Stateless, horizontally scalable architecture: Designed for high availability and scale.
• Automatic executor scaling: The system automatically adjusts the number of executors based on load.
• mTLS authentication: Secure communication using mutual TLS.
• Build without the bytes: Optimization to reduce data transfer requirements.
• Action deduplication / merging: Reduces redundant work by identifying and merging identical build actions.

In addition to the core UI improvements, v2.5.0 introduced several backend and integration capabilities:

• Storage & CDN: Support for serving static files from a CDN and using MinIO as a storage backend.
• Observability: Support for distributed tracing backends such as Jaeger and Google Cloud Trace.
• CI Integration: Buildkite links now point directly to the specific Buildkite job that spawned the invocation.
• Flaky Test Support: Improved explicit callouts for flaky tests and timeouts, along with RBE improvements to reduce flakes caused by external factors like Docker image pulls.

BuildBuddy Enterprise provides advanced capabilities for large-scale build environments, including:

• Authentication: OpenID Connect (OIDC) support for integration with providers like Okta, GSuite, and Auth0.
• Programmatic Access: A dedicated BuildBuddy API for querying build results.
• Remote Build Execution (RBE): Support for custom Docker images.
• Storage Management: Configurable TTL (Time To Live) for build results and cache, with support for persistent build artifact storage.
• Scalability & Availability: High availability (HA) configurations and horizontal scaling using Kubernetes Horizontal Pod Autoscaler (HPA).
• Support: Enterprise-grade support and uptime guarantees.

BuildBuddy provides end-to-end support for CDC across the server, executors, and the cache path:

• Server Side: Implements SplitBlob and SpliceBlob. Chunks are stored as standard CAS entries. The server can optimize transfers by skipping existing chunks and performing parallel transfers of missing ones.
• Executors: BuildBuddy executors (v2.261.0 or newer) can upload large action outputs as chunks directly. They compute chunk digests, call FindMissingBlobs, and upload only missing pieces by reading byte ranges from the original file to avoid high memory usage.
• Compatibility: CDC is enabled automatically for CDC-eligible execution requests. Existing unchunked cache paths remain functional for clients that do not support the new APIs.

The executor image package defines the base container image shipped with the executor release. It contains most system dependencies required by the executor, such as docker and podman.

Note that the actual executor binary and certain Bazel-provisioned tools (like firecracker) are not part of this base Dockerfile; they are added separately via //enterprise/server/cmd/executor:executor_image.

BuildBuddy's Model Context Protocol (MCP) server provides tools that allow AI agents to explore build and test metadata, logs, artifacts, and target statuses without manually constructing API requests. This enables workflows where agents can automatically check failing CI tests, investigate performance issues, or produce diagnostics during CI runs.

Note on Tool Stability: MCP tool names are subject to change. It is recommended to provide agents with generic instructions (e.g., "Explore build data to find the cause of failure") rather than hardcoding specific tool names in agent instructions like AGENTS.md or custom skills.

To maximize the benefits of Bazel's incremental compilation and remote execution, you should modularize your project:

1. Split into many small modules: Large modules force massive recompilations when code changes. Small modules ensure only a minimal portion of the code is recompiled.
2. Aim for a 'wide' build graph: Adjust dependencies so the graph is wide rather than deep. A wider graph allows for more parallel compilation and better utilization of remote execution resources.