Skip to main content

Configuring BuildBuddy

BuildBuddy on-prem is configured using a yaml formatted configuration file.

Command line flag

On startup, BuildBuddy reads this config file which is specified using the --config_file flag. The config file is periodically re-read, although some options like enabling or disabling a cache require a restart to take effect.


If you're running BuildBuddy in a Docker image - you can use Docker's -v flag to map a custom local config file to /config.yaml in the Docker image.

Be sure to replace PATH_TO_YOUR_LOCAL_CONFIG with the path to your custom config file:

docker pull && docker run -p 1985:1985 -p 8080:8080 -v /PATH_TO_YOUR_LOCAL_CONFIG/config.yaml:/config.yaml

Note: If you're using BuildBuddy's Docker image locally and a third party gRPC cache, you'll likely need to add the --network=host flag to your docker run command in order for BuildBuddy to be able to pull test logs and timing information from the external cache.

Option types

There are two types of config options: Required, and Optional.

  • Required - BuildBuddy will not run without these.
  • Optional - They configure optional functionality. BuildBuddy will happily run without them.

Sample configuration files

We maintain a list of sample configuration files that you can copy and paste to get up and running quickly.

Configuration options

Here's a full list of BuildBuddy's configuration sections:


  • App - basic app-level configuration options.
  • Storage - options that determine where BuildBuddy stores build results.
  • Database - options that determine where BuildBuddy stores build metadata.


  • Cache - configuration options for BuildBuddy's built-in Remote Build Cache.
  • Integrations - configure integrations with other services.
  • SSL - configure SSL/TLS certificates and setup.
  • Github - configure your Github integration.
  • Misc - miscellaneous configuration options.

Enterprise only

  • Auth - configure authentication providers.
  • API - configure BuildBuddy API.
  • Org - configure BuildBuddy Organization.


In addition to the config file, some BuildBuddy options (like port number) can only be configured via command line flags.

More information on these flags, see our flags documentation.

Environment variables

Environment variables in the config file are expanded at runtime. You only need to reference your environment variables like this ${ENV_VARIABLE}.