Buildbucket-Swarming integration, aka Swarmbucket


Buildbucket has native integration with Swarming and Recipes. A bucket can define builders and a buildbucket build in such bucket is converted to a swarming task that runs a recipe. The results are reported back to buildbucket when the task compeltes.


There are 3 swarmbucket configuration levels. From global to concrete: application, bucket and build. A more concrete config value can override a global one.


This section is designed for people who manage Buildbucket. Buildbucket users can safely skip it.

Luci-config file services/<buildbucket-app-id>:swarming_task_template.json specifies the body of POST request that buildbucket sends to swarming when creating a task.

In particular it contains the command line parameters. In general, you can specify anything you want, but to run a recipe, see kitchen.


The template may contain parameters of form ${name} in string literals. They will be expanded during task scheduling. Known parameters:

  • bucket: value of build.bucket.
  • builder: value of builder_name build parameter.
  • builder_hash: sha256 hex digest of the bucket and builder.
  • cache_dir: location of the recipe cache directory relative to task rundir.
  • repository: repository URL of the recipe.
  • revision: revision of the recipe.
  • recipe: name of the recipe.
  • properties_json: a JSON string containing build properties.
  • project: LUCI project id that the bucket is defined at, e.g. “chromium”.
  • swarming_hostname: swarming instance hostname, e.g. “” configured in a bucket.

Example: swarming_task_template.json.


If luci-config file services/\<buildbucket-app-id\>:swarming_task_template_canary.json exists then it is used as a task template in a fraction of builds specified by bucket task_template_canary_percentage config value. If it is not configured, then the fraction is the hardcoded value of 10%.

An individual build request can specify canary_preference field value to explicitly opt-in/out of canary. If canary_preference is true, but the canary is not configured on an instance of swarmbucket, such build request will be rejected.

Bucket level

Chrome Operations production buckets that use Swarming integration must have name luci.<project_id>.<suffix>, where project_id is the id of the entry in projects.cfg that points to the repository where the bucket is defined, and suffix is typically try for tryservers and ci for continuous builders.

A bucket entry in buildbucket config may have swarming key, for example:

buckets {
  name: "foobar"

  swarming {
    hostname: ""
    builder_defaults {
      recipe {
        repository: ""
        name: "chromium"
    builders {
      name: "Linux-Release"
      dimensions {
        key: "os"
        value: "Linux"
    builders {
      name: "Windows-Release"
      dimensions {
        key: "os"
        value: "Windows"

For the format and documentation see Swarming message in the project_config.proto. Real world configuration example: “luci.infra.try” bucket

Build level

A buildbucket build can have "swarming" parameter, which is a JSON object with optional properties:

  • "override_builder_cfg": can override builder configuration defined on the server. For example, it can override a dimensions or a recipe ref. See also a section about it below.

Override configuration dynamically

swarming.override_builder_cfg parameter can override builder configuration defined on the server. For example, value

  "dimensions": ["cores:64"]

(re)defines “cores” dimension to be “64” for this particular build.

The format is defined by the Builder message in project_config.proto; in practice, it is JSONPB of the message.


A swarming task created by buildbucket has extra tags:

  • buildbucket_hostname:<hostname>
  • buildbucket_bucket_id:<project_id>/<bucket>, e.g. chromium/try.
  • buildbucket_build_id:<id>
  • buildbucket_template_revision:<template commit hash>
  • buildbucket_template_canary:<1 if created from canary template>
  • recipe_repository:<repo url>
  • recipe_revision:<revision>
  • recipe_name:<name>
  • all tags in swarming_tags of builder config.
  • all tags in build creation request.

A buildbucket build associated with a swarming task has extra tags:

  • swarming_hostname:<hostname>
  • swarming_task_id:<task_id>
  • swarming_tag:<tag> for each swarming task tag, even if it was derived from a buildbucket build tag.
  • swarming_dimension:<dimension> for each dimension.


A swarming task created by buildbucket has extra recipe properties:

  • "$recipe_engine/runtime"["is_luci"] is always true
  • "$recipe_engine/runtime"["is_experimental"] is false unless:
    • The builder has luci_migration_host set to a migration app; AND
    • The build has a “mastername” property; AND
    • The migration app says that LUCI is not Prod for this master+builder combination.

Life of a swarmbucket build

  1. A user schedules a build on bucket "foobar" configured as above. The build has "builder_name": "Linux-Release" parameter.
  2. Linux-Release config is matched. This build is for swarming.
  3. Task template is rendered. Repository URL, recipe and other parameters are expanded to “”, “chromium”, etc.
  4. Swarming task is created.
  5. Build entity is mutated to have extra tags, to point to the task, etc.
  6. Swarming task starts.
  7. Swarming sends a message to buildbucket. Buildbucket marks the build as STARTED.
  8. Swarming task completes. Swarming sends a PubSub message to buildbucket.
  9. Swarming sends a message to buildbucket. Buildbucket marks the build as COMPLETED.