| // 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_dir.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; |
| } |