buildbuddy-api

name

buildbuddy_api

description

Reference for querying BuildBuddy API. Use when investigating failed or slow CI builds, inspecting invocations by commit or branch, reading build or test logs, checking remote execution (RBE) details (exit codes, stderr, worker logs), analyzing cache hit/miss rates, downloading undeclared test outputs from RBE workers, bisecting test failures using target history to find the culprit commit range, viewing aggregated build statistics, triggering workflow re-runs, or getting AI analysis of build failures. Trigger when the user asks "why did this build fail", "show me the build log", "check RBE execution", "get test output from RBE", "what happened in this CI run", "check cache performance", "when did this test start failing", "find the commit that broke this test", "re-run CI", "trigger a workflow", "build stats by branch", "ask BuildBuddy about this failure", or any task that requires fetching data from BuildBuddy.

BuildBuddy API

Prerequisites

All commands require BUILDBUDDY_API_KEY to be set (session hook exports it automatically).

Official bb CLI

The official BuildBuddy CLI (bb) handles build logs and execution details:

# View build log for an invocation (replaces bbapi invocation log)
bb view <invocation-id-or-url> [--lines=100000]

# Fetch cached execution response for a single execution ID
bb execution get <execution-id> [--output=json]

# Download raw blob from CAS by digest
bb download <digest>/<size> [--type=Action|Command]

bbapi CLI

bbapi provides API query features not available in bb:

# Show invocation details (shows child invocation IDs for workflows)
bbapi invocation <invocation-id>

# List recent invocations (auto-detects repo from git remote)
bbapi invocation list [--repo URL] [--count N]

# Download test.log for a specific target (most common for debugging failures)
bbapi target log <invocation-id> <target-label-or-substring>

# List targets in an invocation (auto-resolves workflow/runner IDs to child)
bbapi target <invocation-id> [--filter SUBSTR] [--label LABEL]

# Show pass/fail/flake history for targets (auto-detects group_id)
bbapi target history [--repo URL] [--label LABEL] [--failures-only]

# Show flake statistics for targets (last 7 days)
bbapi target stats [--repo URL]

# Show flake samples for a specific target
bbapi target flakes <target-label> [--repo URL]

# List artifacts, or download one by name match
bbapi artifact <invocation-id> [name-substring]

# List remote executions for an invocation
bbapi execution <invocation-id>

# Search remote executions across invocations
bbapi execution search <query>

# Aggregated invocation statistics (by branch, user, commit, etc.)
bbapi invocation stat [--agg-type branch|user|host|repo|commit|pattern] [--repo URL] [--limit N]

# AI analysis of a build/test failure (works on any invocation, unlike `bb ask`)
# Sends the last ~1000 lines of the build log (from first "ERROR:" onward, max 8KB)
# to OpenAI. Best for build errors with clear error messages in the log tail.
# Less useful for test timeouts (log tail may show unrelated warnings instead).
bbapi ask <invocation-id> [--prompt TEXT]

# List configured BuildBuddy workflows
bbapi workflow

# Trigger a workflow run (auto-detects workflow ID, branch, commit from git)
bbapi workflow run [--workflow-id ID] [--branch BRANCH] [--commit SHA] [--action NAME] [--async]

# Show cache scorecard (per-action hit/miss)
bbapi cache <invocation-id>

# Get metadata for a cached artifact by digest
bbapi cache metadata <digest> <size-bytes>

# Show build performance trends
bbapi trend [--days N] [--repo URL]

All bbapi commands support --json for raw JSON output.

Investigating Failed CI Builds

Typical workflow for debugging a failed CI build:

# 1. Get invocation details — note the Child: line for workflow invocations
bbapi invocation <invocation-id>

# 2. Get the build log to see which tests failed
bb view <invocation-id>

# 3. Download the test.log for a specific failed target
#    Works with both workflow and child invocation IDs (auto-resolves)
bbapi target log <invocation-id> <target-substring>
#    Example: bbapi target log 870a5be1-c296-4792-8c8a-77def20b2dcc test_handlers

Workflow vs Child Invocations

BuildBuddy CI runs use workflow invocations that spawn child invocations. The workflow invocation (command: workflow run) is a wrapper; the child invocation contains the actual bazel test results, targets, and artifacts.

• bbapi invocation shows Child: <child-id> for workflow invocations
• bbapi artifact and bbapi target log auto-resolve workflow invocations to their children — you can pass either the workflow or child ID
• bbapi target also auto-resolves workflow invocations to their children

Artifact Name Matching

bbapi artifact and bbapi target log match against "label/name":

• "test_handlers" matches //x/gatelet/server/auth:test_handlers/test.log
• "test_handlers/test.xml" matches the XML output specifically
• "compositor/test_lifecycle" matches //mcp_infra/compositor:test_lifecycle/test.log

When no match is found, the CLI prints available labels as hints.

Bisecting Test Failures with Target History

When a test is failing and you need to find the commit that broke it, use target history instead of git bisect — BuildBuddy already has all the results:

# 1. Check recent pass/fail history for the target (failures only)
bbapi target history --failures-only --label //path/to:test_target

# 2. Identify the transition point (last pass → first fail)
#    The output shows invocation IDs and commit SHAs for each run

# 3. Narrow to the commit range
git log --oneline <last-pass-commit>..<first-fail-commit>

# 4. Read the test log from the first failing invocation
bbapi target log <first-failing-invocation-id> test_target

This is much faster than git bisect because it doesn't require re-running the test — the results are already in BuildBuddy's database.

Diagnosing Executor Environments

Use bb execute to run one-off commands directly on a BuildBuddy executor to probe the container image, check installed tools, verify library paths, etc. Useful when builds fail due to missing dependencies or environment issues.

# Probe what's in a container image
bb execute \
  -exec_properties=container-image=docker://ghcr.io/agentydragon/rbe-worker:nix-devtools \
  -- bash -c 'gcc --version; python3 --version; ldd --version | head -1'

# Check if a specific library exists
bb execute \
  -exec_properties=container-image=docker://ghcr.io/agentydragon/rbe-worker:latest \
  -- bash -c 'find / -name "libstdc++.so*" 2>/dev/null'

# Test pip wheel compatibility (manylinux tags)
bb execute \
  -exec_properties=container-image=docker://ghcr.io/agentydragon/rbe-worker:latest \
  -- bash -c 'python3 -m pip install --dry-run some-package==1.0'

bb execute runs on the default executor image (Ubuntu 16.04, glibc 2.23) unless you specify -exec_properties=container-image=.... Use -exec_properties=workload-isolation-type=firecracker to test with Firecracker isolation.

Interactive debugging with bb ssh

For interactive debugging, start an SSH server on a BuildBuddy executor:

# On the executor (in one terminal)
bb ssh-server my-debug-session

# Connect from your machine (in another terminal)
bb ssh my-debug-session

This gives a full shell on the executor for investigating build failures, inspecting the filesystem, testing commands interactively, etc.

BuildBuddy Concepts

Group ID: BuildBuddy's organization identifier (e.g., GR7963402054611859571). Scopes API queries to the org's data. Auto-detected by bbapi from a recent invocation's ACL — no manual configuration needed.

Workflow ID: For repos using buildbuddy.yaml + GitHub app, workflow IDs are synthetic: WF#GitRepository:{group_id}:{repo_url}. The bbapi workflow run command auto-constructs this from the detected group_id and repo URL. GetWorkflows returns empty for these repos (it only lists explicitly created workflows).

Raw API Fallback

If bbapi is not available, use the Twirp JSON API at app.buildbuddy.io directly with curl. Read <devinfra/buildbuddy_cli/client.go> for how the CLI talks to the API (Twirp JSON over HTTP). The API key comes from BUILDBUDDY_API_KEY env var, or parse it from ~/.config/bazel/buildbuddy.bazelrc (x-buildbuddy-api-key=...).

Proto definitions for request/response schemas:

• https://github.com/buildbuddy-io/buildbuddy/blob/master/proto/buildbuddy_service.proto (internal, ~70 RPCs)
• https://github.com/buildbuddy-io/buildbuddy/blob/master/proto/api/v1/service.proto (public, 9 endpoints)

Known Limitations

Fork PRs don't have BuildBuddy invocations. GitHub Actions does not pass BUILDBUDDY_API_KEY to workflows triggered by fork pull requests (head repo != base repo). As a result, bazel-check and bazel-test are skipped entirely on fork PRs (see #787). When investigating a failed fork PR, BuildBuddy has no record of the run — check GitHub Actions logs directly instead.