go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/buildbucket/proto/build.proto

// Copyright 2018 The LUCI Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package buildbucket.v2;

option go_package = "go.chromium.org/luci/buildbucket/proto;buildbucketpb";

import "google/api/field_behavior.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/struct.proto";
import "go.chromium.org/luci/buildbucket/proto/build_field_visibility.proto";
import "go.chromium.org/luci/buildbucket/proto/builder_common.proto";
import "go.chromium.org/luci/buildbucket/proto/common.proto";
import "go.chromium.org/luci/buildbucket/proto/field_option.proto";
import "go.chromium.org/luci/buildbucket/proto/step.proto";
import "go.chromium.org/luci/buildbucket/proto/task.proto";
import "go.chromium.org/luci/resultdb/proto/v1/invocation.proto";

// A single build, identified by an int64 ID.
// Belongs to a builder.
//
// RPC: see Builds service for build creation and retrieval.
// Some Build fields are marked as excluded from responses by default.
// Use "mask" request field to specify that a field must be included.
//
// BigQuery: this message also defines schema of a BigQuery table of completed
// builds. A BigQuery row is inserted soon after build ends, i.e. a row
// represents a state of a build at completion time and does not change after
// that. All fields are included.
//
// Next id: 36.
message Build {
  // Defines what to build/test.
  //
  // Behavior of a build executable MAY depend on Input.
  // It MAY NOT modify its behavior based on anything outside of Input.
  // It MAY read non-Input fields to display for debugging or to pass-through to
  // triggered builds. For example the "tags" field may be passed to triggered
  // builds, or the "infra" field may be printed for debugging purposes.
  message Input {
    // Arbitrary JSON object. Available at build run time.
    //
    // RPC: By default, this field is excluded from responses.
    //
    // V1 equivalent: corresponds to "properties" key in "parameters_json".
    google.protobuf.Struct properties = 1;

    // The Gitiles commit to run against.
    // Usually present in CI builds, set by LUCI Scheduler.
    // If not present, the build may checkout "refs/heads/master".
    // NOT a blamelist.
    //
    // V1 equivalent: supersedes "revision" property and "buildset"
    // tag that starts with "commit/gitiles/".
    GitilesCommit gitiles_commit = 2 [ (visible_with) = BUILDS_GET_LIMITED_PERMISSION ];

    // Gerrit patchsets to run against.
    // Usually present in tryjobs, set by CQ, Gerrit, git-cl-try.
    // Applied on top of gitiles_commit if specified, otherwise tip of the tree.
    //
    // V1 equivalent: supersedes patch_* properties and "buildset"
    // tag that starts with "patch/gerrit/".
    repeated GerritChange gerrit_changes = 3 [ (visible_with) = BUILDS_GET_LIMITED_PERMISSION ];

    // DEPRECATED
    //
    // Equivalent to `"luci.non_production" in experiments`.
    //
    // See `Builder.experiments` for well-known experiments.
    bool experimental = 5;

    // The sorted list of experiments enabled on this build.
    //
    // See `Builder.experiments` for a detailed breakdown on how experiments
    // work, and go/buildbucket-settings.cfg for the current state of global
    // experiments.
    repeated string experiments = 6;
  }

  // Result of the build executable.
  message Output {
    reserved 4; // critical, was moved to Build.

    // Arbitrary JSON object produced by the build.
    //
    // In recipes, use step_result.presentation.properties to set these,
    // for example
    //
    //   step_result = api.step(['echo'])
    //   step_result.presentation.properties['foo'] = 'bar'
    //
    // More docs: https://chromium.googlesource.com/infra/luci/recipes-py/+/HEAD/doc/old_user_guide.md#Setting-properties
    //
    // V1 equivalent: corresponds to "properties" key in
    // "result_details_json".
    // In V1 output properties are not populated until build ends.
    google.protobuf.Struct properties = 1;

    // Build checked out and executed on this commit.
    //
    // Should correspond to Build.Input.gitiles_commit.
    // May be present even if Build.Input.gitiles_commit is not set, for example
    // in cron builders.
    //
    // V1 equivalent: this supersedes all got_revision output property.
    GitilesCommit gitiles_commit = 3;

    // Logs produced by the build script, typically "stdout" and "stderr".
    repeated Log logs = 5;

    // Build status which is reported by the client via StartBuild or UpdateBuild.
    Status status = 6;
    StatusDetails status_details = 7;
    // Deprecated. Use summary_markdown instead.
    string summary_html = 8 [deprecated = true];
    string summary_markdown = 2;
  }

  reserved 13; // infra_failure_reason was moved into status_details.
  reserved 14; // cancel_reason was moved into status_details.

  // Identifier of the build, unique per LUCI deployment.
  // IDs are monotonically decreasing.
  int64 id = 1 [ (google.api.field_behavior) = OUTPUT_ONLY,
                 (visible_with) = BUILDS_LIST_PERMISSION ];

  // Required. The builder this build belongs to.
  //
  // Tuple (builder.project, builder.bucket) defines build ACL
  // which may change after build has ended.
  BuilderID builder = 2 [ (buildbucket.v2.create_build_field_option).field_behavior = REQUIRED,
                          (visible_with) = BUILDS_GET_LIMITED_PERMISSION ];

  // Information of the builder, propagated from builder config.
  //
  // The info captures the state of the builder at creation time.
  // If any information is updated, all future builds will have the new
  // information, while the historical builds persist the old information.
  message BuilderInfo {
    string description = 1;

    // TODO(crbug.com/1093655): add builder tags.
  }
  BuilderInfo builder_info = 34 [ (google.api.field_behavior) = OUTPUT_ONLY ];

  // Human-readable identifier of the build with the following properties:
  // - unique within the builder
  // - a monotonically increasing number
  // - mostly contiguous
  // - much shorter than id
  //
  // Caution: populated (positive number) iff build numbers were enabled
  // in the builder configuration at the time of build creation.
  //
  // Caution: Build numbers are not guaranteed to be contiguous.
  // There may be gaps during outages.
  //
  // Caution: Build numbers, while monotonically increasing, do not
  // necessarily reflect source-code order. For example, force builds
  // or rebuilds can allocate new, higher, numbers, but build an older-
  // than-HEAD version of the source.
  int32 number = 3 [ (google.api.field_behavior) = OUTPUT_ONLY,
                     (visible_with) = BUILDS_GET_LIMITED_PERMISSION ];

  // Verified LUCI identity that created this build.
  string created_by = 4 [ (google.api.field_behavior) = OUTPUT_ONLY ];

  // Redirect url for the build.
  string view_url = 5;

  // Verified LUCI identity that canceled this build.
  //
  // Special values:
  // * buildbucket: The build is canceled by buildbucket. This can happen if the
  // build's parent has ended, and the build cannot outlive its parent.
  // * backend: The build's backend task is canceled. For example the build's
  // Swarming task is killed.
  string canceled_by = 23 [ (google.api.field_behavior) = OUTPUT_ONLY ];

  // When the build was created.
  google.protobuf.Timestamp create_time = 6
      [ (google.api.field_behavior) = OUTPUT_ONLY,
        (visible_with) = BUILDS_GET_LIMITED_PERMISSION ];
  // When the build started.
  // Required iff status is STARTED, SUCCESS or FAILURE.
  google.protobuf.Timestamp start_time = 7
      [ (google.api.field_behavior) = OUTPUT_ONLY,
        (visible_with) = BUILDS_GET_LIMITED_PERMISSION ];
  // When the build ended.
  // Present iff status is terminal.
  // MUST NOT be before start_time.
  google.protobuf.Timestamp end_time = 8
      [ (google.api.field_behavior) = OUTPUT_ONLY,
        (visible_with) = BUILDS_GET_LIMITED_PERMISSION ];
  // When the build was most recently updated.
  //
  // RPC: can be > end_time if, e.g. new tags were attached to a completed
  // build.
  google.protobuf.Timestamp update_time = 9
      [ (google.api.field_behavior) = OUTPUT_ONLY,
        (visible_with) = BUILDS_GET_LIMITED_PERMISSION ];
  // When the cancel process of the build started.
  // Note it's not the time that the cancellation completed, which would be
  // tracked by end_time.
  //
  // During the cancel process, the build still accepts updates.
  //
  // bbagent checks this field at the frequency of
  // buildbucket.MinUpdateBuildInterval. When bbagent sees the build is in
  // cancel process, there are two states:
  //  * it has NOT yet started the exe payload,
  //  * it HAS started the exe payload.
  //
  // In the first state, bbagent will immediately terminate the build without
  // invoking the exe payload at all.
  //
  // In the second state, bbagent will send SIGTERM/CTRL-BREAK to the exe
  // (according to the deadline protocol described in
  // https://chromium.googlesource.com/infra/luci/luci-py/+/HEAD/client/LUCI_CONTEXT.md).
  // After grace_period it will then try to kill the exe.
  //
  // NOTE: There is a race condition here; If bbagent starts the luciexe and
  // then immediately notices that the build is canceled, it's possible that
  // bbagent can send SIGTERM/CTRL-BREAK to the exe before that exe sets up
  // interrupt handlers. There is a bug on file (crbug.com/1311821)
  // which we plan to implement at some point as a mitigation for this.
  //
  // Additionally, the Buildbucket service itself will launch an asynchronous
  // task to terminate the build via the backend API (e.g. Swarming cancellation)
  // if bbagent cannot successfully terminate the exe in time.
  google.protobuf.Timestamp cancel_time = 32
      [ (google.api.field_behavior) = OUTPUT_ONLY,
        (visible_with) = BUILDS_GET_LIMITED_PERMISSION ];

  // Status of the build.
  // Must be specified, i.e. not STATUS_UNSPECIFIED.
  //
  // RPC: Responses have most current status.
  //
  // BigQuery: Final status of the build. Cannot be SCHEDULED or STARTED.
  Status status = 12 [ (buildbucket.v2.create_build_field_option).field_behavior = OUTPUT_ONLY,
                       (visible_with) = BUILDS_LIST_PERMISSION ];

  // Human-readable summary of the build in Markdown format
  // (https://spec.commonmark.org/0.28/).
  // Explains status.
  // Up to 4 KB.
  string summary_markdown = 20 [ (buildbucket.v2.create_build_field_option).field_behavior = OUTPUT_ONLY ];

  // Markdown reasoning for cancelling the build.
  // Human readable and should be following https://spec.commonmark.org/0.28/.
  string cancellation_markdown = 33 [ (buildbucket.v2.create_build_field_option).field_behavior = OUTPUT_ONLY ];

  // If NO, then the build status SHOULD NOT be used to assess correctness of
  // the input gitiles_commit or gerrit_changes.
  // For example, if a pre-submit build has failed, CQ MAY still land the CL.
  // For example, if a post-submit build has failed, CLs MAY continue landing.
  Trinary critical = 21 [ (visible_with) = BUILDS_GET_LIMITED_PERMISSION ];

  // Machine-readable details of the current status.
  // Human-readable status reason is available in summary_markdown.
  StatusDetails status_details = 22
      [ (buildbucket.v2.create_build_field_option).field_behavior = OUTPUT_ONLY,
        (visible_with) = BUILDS_LIST_PERMISSION ];

  // Input to the build executable.
  Input input = 15 [ (buildbucket.v2.create_build_field_option).field_behavior = REQUIRED ];

  // Output of the build executable.
  // SHOULD depend only on input field and NOT other fields.
  // MUST be unset if build status is SCHEDULED.
  //
  // RPC: By default, this field is excluded from responses.
  // Updated while the build is running and finalized when the build ends.
  Output output = 16 [ (buildbucket.v2.create_build_field_option).field_behavior = OUTPUT_ONLY ];

  // Current list of build steps.
  // Updated as build runs.
  //
  // May take up to 1MB after zlib compression.
  // MUST be unset if build status is SCHEDULED.
  //
  // RPC: By default, this field is excluded from responses.
  repeated Step steps = 17 [ (buildbucket.v2.create_build_field_option).field_behavior = OUTPUT_ONLY ];

  // Build infrastructure used by the build.
  //
  // RPC: By default, this field is excluded from responses.
  BuildInfra infra = 18 [ (buildbucket.v2.create_build_field_option).field_behavior = REQUIRED ];

  // Arbitrary annotations for the build.
  // One key may have multiple values, which is why this is not a map<string,string>.
  // Indexed by the server, see also BuildPredicate.tags.
  repeated StringPair tags = 19;

  // What to run when the build is ready to start.
  Executable exe = 24 [ (buildbucket.v2.create_build_field_option).field_behavior = REQUIRED ];

  // DEPRECATED
  //
  // Equivalent to `"luci.buildbucket.canary_software" in input.experiments`.
  //
  // See `Builder.experiments` for well-known experiments.
  bool canary = 25;

  // Maximum build pending time.
  // If the timeout is reached, the build is marked as INFRA_FAILURE status
  // and both status_details.{timeout, resource_exhaustion} are set.
  google.protobuf.Duration scheduling_timeout = 26;

  // Maximum build execution time.
  //
  // Not to be confused with scheduling_timeout.
  //
  // If the timeout is reached, the task will be signaled according to the
  // `deadline` section of
  // https://chromium.googlesource.com/infra/luci/luci-py/+/HEAD/client/LUCI_CONTEXT.md
  // and status_details.timeout is set.
  //
  // The task will have `grace_period` amount of time to handle cleanup
  // before being forcefully terminated.
  google.protobuf.Duration execution_timeout = 27;

  // Amount of cleanup time after execution_timeout.
  //
  // After being signaled according to execution_timeout, the task will
  // have this duration to clean up before being forcefully terminated.
  //
  // The signalling process is explained in the `deadline` section of
  // https://chromium.googlesource.com/infra/luci/luci-py/+/HEAD/client/LUCI_CONTEXT.md.
  google.protobuf.Duration grace_period = 29;

  // If set, swarming was requested to wait until it sees at least one bot
  // report a superset of the build's requested dimensions.
  bool wait_for_capacity = 28;

  // Flag to control if the build can outlive its parent.
  //
  // This field is only meaningful if the build has ancestors.
  // If the build has ancestors and the value is false, it means that the build
  // SHOULD reach a terminal status (SUCCESS, FAILURE, INFRA_FAILURE or
  // CANCELED) before its parent. If the child fails to do so, Buildbucket will
  // cancel it some time after the parent build reaches a terminal status.
  //
  // A build that can outlive its parent can also outlive its parent's ancestors.
  bool can_outlive_parent = 30 [ (visible_with) = BUILDS_LIST_PERMISSION ];

  // IDs of the build's ancestors. This includes all parents/grandparents/etc.
  // This is ordered from top-to-bottom so `ancestor_ids[0]` is the root of
  // the builds tree, and `ancestor_ids[-1]` is this build's immediate parent.
  // This does not include any "siblings" at higher levels of the tree, just
  // the direct chain of ancestors from root to this build.
  repeated int64 ancestor_ids = 31 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (visible_with) = BUILDS_LIST_PERMISSION ];

  // If UNSET, retrying the build is implicitly allowed;
  // If YES, retrying the build is explicitly allowed;
  // If NO, retrying the build is explicitly disallowed,
  //   * any UI displaying the build should remove "retry" button(s),
  //   * ScheduleBuild using the build as template should fail,
  //   * but the build can still be synthesized by SynthesizeBuild.
  Trinary retriable = 35;
}

message InputDataRef {
  message CAS {
    // Full name of RBE-CAS instance. `projects/{project_id}/instances/{instance}`.
    // e.g. projects/chromium-swarm/instances/default_instance
    string cas_instance = 1;

    // This is a [Digest][build.bazel.remote.execution.v2.Digest] of a blob on
    // RBE-CAS. See the explanations at the original definition.
    // https://github.com/bazelbuild/remote-apis/blob/77cfb44a88577a7ade5dd2400425f6d50469ec6d/build/bazel/remote/execution/v2/remote_execution.proto#L753-L791
    message Digest {
      string hash = 1;
      int64 size_bytes = 2;
    }

    Digest digest = 2;
  }

  message CIPD {
    string server = 1;

    message PkgSpec {
      // Package MAY include CIPD variables, including conditional variables like
      // `${os=windows}`. Additionally, version may be a ref or a tag.
      string package = 1;
      string version = 2;
    }
    repeated PkgSpec specs = 2;
  }

  oneof data_type {
    CAS cas = 1;
    CIPD cipd = 2;
  }

  // TODO(crbug.com/1266060): TBD. `on_path` may need to move out to be incorporated into a field which captures other envvars.
  // Subdirectories relative to the root of `ref` which should be set as a prefix to
  // the $PATH variable.
  //
  // A substitute of `env_prefixes` in SwarmingRpcsTaskProperties field -
  // https://chromium.googlesource.com/infra/luci/luci-go/+/0048a84944e872776fba3542aa96d5943ae64bab/common/api/swarming/swarming/v1/swarming-gen.go#1495
  repeated string on_path = 3;

  reserved 4; // purpose, replaced by agent.data_purposes.
}

message ResolvedDataRef {
  message Timing {
    google.protobuf.Duration fetch_duration = 1;
    google.protobuf.Duration install_duration = 2;
  }

  message CAS {
    // TODO(crbug.com/1266060): potential fields can be
    // int64 cache_hits = ?;
    // int64 cache_hit_size = ?:
    // int64 cache_misses = ?;
    // int64 cache_miss_size = ?;
    // need more thinking and better to determine when starting writing code
    // to download binaries in bbagent.
    Timing timing = 1;
  }

  message CIPD {
    message PkgSpec {
      // True if this package wasn't installed because `package` contained a
      // non-applicable conditional (e.g. ${os=windows} on a mac machine).
      bool skipped = 1;

      string package = 2;  // fully resolved
      string version = 3;  // fully resolved

      Trinary was_cached = 4;
      Timing timing = 5;  // optional
    }

    repeated PkgSpec specs = 2;
  }

  // TODO(crbug.com/1266060): if we have local caches here, report if they were cached
  // and how big they were when they were mapped in.

  oneof data_type {
    CAS cas = 1;
    CIPD cipd = 2;
  }
}

// Build infrastructure that was used for a particular build.
message BuildInfra {

  // Buildbucket-specific information, captured at the build creation time.
  message Buildbucket {
    // bbagent will interpret Agent.input, as well as update Agent.output.
    message Agent {
      // Source describes where the Agent should be fetched from.
      message Source {
        message CIPD {
          // The CIPD package to use for the agent.
          //
          // Must end in "/${platform}" with no other CIPD variables.
          //
          // If using an experimental agent binary, please make sure the package
          // prefix has been configured here -
          // https://chrome-internal.googlesource.com/infradata/config/+/refs/heads/main/configs/chrome-infra-packages/bootstrap.cfg
          string package = 1;

          // The CIPD version to use for the agent.
          string version = 2;

          // The CIPD server to use.
          string server = 3;

          // maps ${platform} -> instance_id for resolved agent packages.
          //
          // Will be overwritten at CreateBuild time, should be left empty
          // when creating a new Build.
          map<string, string> resolved_instances = 4 [ (google.api.field_behavior) = OUTPUT_ONLY ];
        }

        oneof data_type {
          CIPD cipd = 1;
        }
        // Other source mechanisms could be added in the future, such as GCS
        // CAS or direct-download URLs. These would need to have a map of
        // platform -> details.
      }
      message Input {
        // Maps relative-to-root directory to the data.
        //
        // For now, data is only allowed at the 'leaves', e.g. you cannot
        // specify data at "a/b/c" and "a/b" (but "a/b/c" and "a/q" would be OK).
        // All directories beginning with "luci." are reserved for Buildbucket's own use.
        //
        // TODO(crbug.com/1266060): Enforce the above constraints in a later phase.
        // Currently users don't have the flexibility to set the parent directory path.
        map<string, InputDataRef> data = 1;

        // Maps relative-to-root directory to the cipd package itself.
        // This is the CIPD client itself and  should be downloaded first so that
        // the packages in the data field above can be downloaded.
        map<string, InputDataRef> cipd_source = 2;
      }
      message Output {
        // Maps relative-to-root directory to the fully-resolved ref.
        //
        // This will always have 1:1 mapping to Agent.Input.data
        map<string, ResolvedDataRef> resolved_data = 1;

        Status status = 2;
        StatusDetails status_details = 3;
        // Deprecated. Use summary_markdown instead.
        string summary_html = 4 [deprecated = true];

        // The agent's resolved CIPD ${platform} (e.g. "linux-amd64",
        // "windows-386", etc.).
        //
        // This is trivial for bbagent to calculate (unlike trying to embed
        // its cipd package version inside or along with the executable).
        // Buildbucket is doing a full package -> instance ID resolution at
        // CreateBuild time anyway, so Agent.Source.resolved_instances
        // will give the mapping from `agent_platform` to a precise instance_id
        // which was used.
        string agent_platform = 5;

        // Total installation duration for all input data. Currently only record
        // cipd packages installation time.
        google.protobuf.Duration total_duration = 6;
        string summary_markdown = 7;
      }

      // TODO(crbug.com/1297809): for a long-term solution, we may need to add
      // a top-level `on_path` array field in the input and read the value from
      // configuration files (eg.settings.cfg, builder configs). So it can store
      // the intended order of PATH env var. Then the per-inputDataRef level
      // `on_path` field will be deprecated.
      // Currently, the new BBagent flow merges all inputDataRef-level `on_path`
      // values and sort. This mimics the same behavior of PyBB backend in order
      // to have the cipd_installation migration to roll out first under a minimal risk.
      Input input = 1 [ (buildbucket.v2.create_build_field_option).field_behavior = REQUIRED ];
      Output output = 2 [ (buildbucket.v2.create_build_field_option).field_behavior = OUTPUT_ONLY ];
      Source source = 3 [ (buildbucket.v2.create_build_field_option).field_behavior = REQUIRED ];

      enum Purpose {
        // No categorized/known purpose.
        PURPOSE_UNSPECIFIED = 0;

        // This path contains the contents of the build's `exe.cipd_package`.
        PURPOSE_EXE_PAYLOAD = 1;

        // This path contains data specifically for bbagent's own use.
        //
        // There's a proposal currently to add `nsjail` support to bbagent, and it
        // would need to bring a copy of `nsjail` in order to run the user binary
        // but we wouldn't necessarily want to expose it to the user binary.
        PURPOSE_BBAGENT_UTILITY = 2;
      }

      // Maps the relative-to-root directory path in both `input` and `output`
      // to the Purpose of the software in that directory.
      //
      // If a path is not listed here, it is the same as PURPOSE_UNSPECIFIED.
      map<string, Purpose> purposes = 4;

      // Cache for the cipd client.
      // The cache name should be in the format like `cipd_client_<sha(client_version)>`.
      CacheEntry cipd_client_cache = 5;
      // Cache for the cipd packages.
      // The cache name should be in the format like `cipd_cache_<sha(task_service_account)>`.
      CacheEntry cipd_packages_cache = 6;
    }

    reserved 4; // field "canary" was moved to Build message.

    // Version of swarming task template. Defines
    // versions of kitchen, git, git wrapper, python, vpython, etc.
    string service_config_revision = 2;
    // Properties that were specified in ScheduleBuildRequest to create this
    // build.
    //
    // In particular, CQ uses this to decide whether the build created by
    // someone else is appropriate for CQ, e.g. it was created with the same
    // properties that CQ would use.
    google.protobuf.Struct requested_properties = 5;

    // Dimensions that were specified in ScheduleBuildRequest to create this
    // build.
    repeated RequestedDimension requested_dimensions = 6;

    // Buildbucket hostname, e.g. "cr-buildbucket.appspot.com".
    string hostname = 7;

    enum ExperimentReason {
      // This value is unused (i.e. if you see this, it's a bug).
      EXPERIMENT_REASON_UNSET = 0;

      // This experiment was configured from the 'default_value' of a global
      // experiment.
      //
      // See go/buildbucket-settings.cfg for the list of global experiments.
      EXPERIMENT_REASON_GLOBAL_DEFAULT = 1;

      // This experiment was configured from the Builder configuration.
      EXPERIMENT_REASON_BUILDER_CONFIG = 2;

      // This experiment was configured from the 'minimum_value' of a global
      // experiment.
      //
      // See go/buildbucket-settings.cfg for the list of global experiments.
      EXPERIMENT_REASON_GLOBAL_MINIMUM = 3;

      // This experiment was explicitly set from the ScheduleBuildRequest.
      EXPERIMENT_REASON_REQUESTED = 4;

      // This experiment is inactive and so was removed from the Build.
      //
      // See go/buildbucket-settings.cfg for the list of global experiments.
      EXPERIMENT_REASON_GLOBAL_INACTIVE = 5;
    }

    // This contains a map of all the experiments involved for this build, as
    // well as which bit of configuration lead to them being set (or unset).
    //
    // Note that if the reason here is EXPERIMENT_REASON_GLOBAL_INACTIVE,
    // then that means that the experiment is completely disabled and has no
    // effect, but your builder or ScheduleBuildRequest still indicated that
    // the experiment should be set. If you see this, then please remove it
    // from your configuration and/or requests.
    map<string, ExperimentReason> experiment_reasons = 8;

    // The agent binary (bbagent or kitchen) resolutions Buildbucket made for this build.
    // This includes all agent_executable references supplied to
    // the TaskBackend in "original" (CIPD) form, to facilitate debugging.
    // DEPRECATED: Use agent.source instead.
    map<string, ResolvedDataRef> agent_executable = 9 [deprecated = true];

    Agent agent = 10 [ (buildbucket.v2.create_build_field_option).field_behavior = REQUIRED ];

    repeated string known_public_gerrit_hosts = 11;

    // Flag for if the build should have a build number.
    bool build_number = 12;
  }

  // Swarming-specific information.
  //
  // Next ID: 10.
  message Swarming {
    // Describes a cache directory persisted on a bot.
    //
    // If a build requested a cache, the cache directory is available on build
    // startup. If the cache was present on the bot, the directory contains
    // files from the previous run on that bot.
    // The build can read/write to the cache directory while it runs.
    // After build completes, the cache directory is persisted.
    // The next time another build requests the same cache and runs on the same
    // bot, the files will still be there (unless the cache was evicted,
    // perhaps due to disk space reasons).
    //
    // One bot can keep multiple caches at the same time and one build can request
    // multiple different caches.
    // A cache is identified by its name and mapped to a path.
    //
    // If the bot is running out of space, caches are evicted in LRU manner
    // before the next build on this bot starts.
    //
    // Builder cache.
    //
    // Buildbucket implicitly declares cache
    //   {"name": "<hash(project/bucket/builder)>", "path": "builder"}.
    // This means that any LUCI builder has a "personal disk space" on the bot.
    // Builder cache is often a good start before customizing caching.
    // In recipes, it is available at api.buildbucket.builder_cache_path.
    //
    message CacheEntry {
      // Identifier of the cache. Required. Length is limited to 128.
      // Must be unique in the build.
      //
      // If the pool of swarming bots is shared among multiple LUCI projects and
      // projects use same cache name, the cache will be shared across projects.
      // To avoid affecting and being affected by other projects, prefix the
      // cache name with something project-specific, e.g. "v8-".
      string name = 1;

      // Relative path where the cache in mapped into. Required.
      //
      // Must use POSIX format (forward slashes).
      // In most cases, it does not need slashes at all.
      //
      // In recipes, use api.path['cache'].join(path) to get absolute path.
      //
      // Must be unique in the build.
      string path = 2;

      // Duration to wait for a bot with a warm cache to pick up the
      // task, before falling back to a bot with a cold (non-existent) cache.
      //
      // The default is 0, which means that no preference will be chosen for a
      // bot with this or without this cache, and a bot without this cache may
      // be chosen instead.
      //
      // If no bot has this cache warm, the task will skip this wait and will
      // immediately fallback to a cold cache request.
      //
      // The value must be multiples of 60 seconds.
      google.protobuf.Duration wait_for_warm_cache = 3;

      // Environment variable with this name will be set to the path to the cache
      // directory.
      string env_var = 4;
    }

    // Swarming hostname, e.g. "chromium-swarm.appspot.com".
    // Populated at the build creation time.
    string hostname = 1 [ (buildbucket.v2.create_build_field_option).field_behavior = REQUIRED ];

    // Swarming task id.
    // Not guaranteed to be populated at the build creation time.
    string task_id = 2 [ (google.api.field_behavior) = OUTPUT_ONLY ];

    // Swarming run id of the parent task from which this build is triggered.
    // If set, swarming promises to ensure this build won't outlive its parent
    // swarming task (which may or may not itself be a Buildbucket build).
    // Populated at the build creation time.
    string parent_run_id = 9;

    // Task service account email address.
    // This is the service account used for all authenticated requests by the
    // build.
    string task_service_account = 3;

    // Priority of the task. The lower the more important.
    // Valid values are [20..255].
    int32 priority = 4;

    // Swarming dimensions for the task.
    repeated RequestedDimension task_dimensions = 5;

    // Swarming dimensions of the bot used for the task.
    repeated StringPair bot_dimensions = 6;

    // Caches requested by this build.
    repeated CacheEntry caches = 7;
  }

  // LogDog-specific information.
  message LogDog {
    // LogDog hostname, e.g. "logs.chromium.org".
    string hostname = 1 [ (buildbucket.v2.create_build_field_option).field_behavior = REQUIRED ];

    // LogDog project, e.g. "chromium".
    // Typically matches Build.builder.project.
    string project = 2;

    // A slash-separated path prefix shared by all logs and artifacts of this
    // build.
    // No other build can have the same prefix.
    // Can be used to discover logs and/or load log contents.
    string prefix = 3;
  }

  // Recipe-specific information.
  message Recipe {
    // CIPD package name containing the recipe used to run this build.
    string cipd_package = 1;

    // Name of the recipe used to run this build.
    string name = 2;
  }

  // ResultDB-specific information.
  message ResultDB {
    // Hostname of the ResultDB instance, such as "results.api.cr.dev".
    string hostname = 1 [ (buildbucket.v2.create_build_field_option).field_behavior = REQUIRED ];

    // Name of the invocation for results of this build.
    // Typically "invocations/build:<build_id>".
    string invocation = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Whether to enable ResultDB:Buildbucket integration.
    bool enable = 3;

    // Configuration for exporting test results to BigQuery.
    // This can have multiple values to export results to multiple BigQuery
    // tables, or to support multiple test result predicates.
    repeated luci.resultdb.v1.BigQueryExport bq_exports = 4;

    // Deprecated. Any values specified here are ignored.
    luci.resultdb.v1.HistoryOptions history_options = 5;
  }

  // Led specific information.
  message Led {
    // The original bucket this led build is shadowing.
    string shadowed_bucket = 1;
  }

  // BBAgent-specific information.
  //
  // All paths are relateive to bbagent's working directory, and must be delimited
  // with slashes ("/"), regardless of the host OS.
  message BBAgent {
    // BBAgent-specific input.
    message Input {
      // CIPD Packages to make available for this build.
      message CIPDPackage {
        // Name of this CIPD package.
        //
        // Required.
        string name = 1;

        // CIPD package version.
        //
        // Required.
        string version = 2;

        // CIPD server to fetch this package from.
        //
        // Required.
        string server = 3;

        // Path where this CIPD package should be installed.
        //
        // Required.
        string path = 4;
      }

      repeated CIPDPackage cipd_packages = 1;
    }
    // Path to the base of the user executable package.
    //
    // Required.
    string payload_path = 1;

    // Path to a directory where each subdirectory is a cache dir.
    //
    // Required.
    string cache_dir = 2;

    // List of Gerrit hosts to force git authentication for.
    //
    // By default public hosts are accessed anonymously, and the anonymous access
    // has very low quota. Context needs to know all such hostnames in advance to
    // be able to force authenticated access to them.
    repeated string known_public_gerrit_hosts = 3 [deprecated = true];

    // DEPRECATED: Use build.Infra.Buildbucket.Agent.Input instead.
    Input input = 4 [deprecated = true];
  }

  // Backend-specific information.
  message Backend {
    // Configuration supplied to the backend at the time it was instructed to
    // run this build.
    google.protobuf.Struct config = 1;

    // Current backend task status.
    // Updated as build runs.
    Task task = 2;

    // Caches requested by this build.
    repeated CacheEntry caches = 3;

    // Dimensions for the task.
    repeated RequestedDimension task_dimensions = 5;

    // Hostname is the hostname for the backend itself.
    string hostname = 6;
  }

  Buildbucket buildbucket = 1 [ (buildbucket.v2.create_build_field_option).field_behavior = REQUIRED ];
  Swarming swarming = 2;
  LogDog logdog = 3 [ (buildbucket.v2.create_build_field_option).field_behavior = REQUIRED ];
  Recipe recipe = 4;
  ResultDB resultdb = 5 [ (visible_with) = BUILDS_GET_LIMITED_PERMISSION ];
  BBAgent bbagent = 6;
  Backend backend = 7;
  // It should only be set for led builds.
  Led led = 8;
}