| // Copyright 2018 The Swarming Authors. All rights reserved. |
| // Use of this source code is governed by the Apache v2.0 license that can be |
| // found in the LICENSE file. |
| |
| syntax = "proto3"; |
| |
| package buildbucket.v2; |
| |
| option go_package = "go.chromium.org/luci/buildbucket/proto;buildbucketpb"; |
| |
| import "google/protobuf/field_mask.proto"; |
| import "google/protobuf/struct.proto"; |
| import "google/rpc/status.proto"; |
| import "go.chromium.org/luci/buildbucket/proto/common.proto"; |
| import "go.chromium.org/luci/buildbucket/proto/build.proto"; |
| import "go.chromium.org/luci/buildbucket/proto/notification.proto"; |
| |
| // Manages builds. |
| // |
| // Buildbot: To simplify V1->V2 API transition for clients, buildbucket.v2.Builds |
| // service has some support for non-LUCI builds. Most of such builds are |
| // Buildbot builds and this documentation refers to them as such, but they also |
| // include non-Buildbot non-LUCI builds (e.g. Skia builds). |
| // See "Buildbot" paragraph in each RPC comment. |
| service Builds { |
| // Gets a build. |
| // |
| // By default the returned build does not include all fields. |
| // See GetBuildRequest.fields. |
| // |
| // Buildbot: if the specified build is a buildbot build, converts it to Build |
| // message with the following rules: |
| // * bucket names are full, e.g. "master.chromium". Note that LUCI buckets |
| // in v2 are shortened, e.g. "ci". |
| // * if a v2 Build field does not make sense in V1, it is unset/empty. |
| // * step support is not implemented for Buildbot builds. |
| // Note that it does not support getting a buildbot build by build number. |
| rpc GetBuild(GetBuildRequest) returns (Build) {}; |
| |
| // Searches for builds. |
| // |
| // Buildbot: can return Buildbot builds, see GetBuild for conversion rules. |
| // For example, response may include a mix of LUCI and Buildbot builds if the |
| // predicate is a CL. |
| // Cannot search in a buildbot bucket or buildbot builder, e.g. |
| // { |
| // "predicate": { |
| // "builder": { |
| // "project": "chromium", |
| // "bucket": "master.chromium", |
| // "builder": "linux-rel" |
| // } |
| // } |
| // } |
| // will look for builds in "master.chromium" LUCI bucket which probably does |
| // not exist. |
| rpc SearchBuilds(SearchBuildsRequest) returns (SearchBuildsResponse) {}; |
| |
| // Updates a build. Returns an empty build. |
| // |
| // RPC metadata must include "X-Build-Token" key with a token |
| // generated by the server when scheduling the build. |
| rpc UpdateBuild(UpdateBuildRequest) returns (Build) {}; |
| |
| // Schedules a new build. |
| // The requester must have at least SCHEDULER role in the destination bucket. |
| rpc ScheduleBuild(ScheduleBuildRequest) returns (Build) {}; |
| |
| // Cancels a build. |
| // The requester must have at least SCHEDULER role in the destination bucket. |
| rpc CancelBuild(CancelBuildRequest) returns (Build) {}; |
| |
| // Executes multiple requests in a batch. |
| // The response code is always OK. |
| rpc Batch(BatchRequest) returns (BatchResponse) {}; |
| } |
| |
| // A request message for GetBuild rpc. |
| message GetBuildRequest { |
| // Build id. |
| // Mutually exclusive with builder and number. |
| int64 id = 1; |
| |
| // Builder of the build. |
| // Requires number. Mutually exclusive with id. |
| BuilderID builder = 2; |
| // Build number. |
| // Requires builder. Mutually exclusive with id. |
| int32 build_number = 3; |
| |
| // Fields to include in the response. |
| // If not set, the default mask is used, see Build message comments for the |
| // list of fields returned by default. |
| // |
| // Supports advanced semantics, see |
| // https://chromium.googlesource.com/infra/luci/luci-py/+/f9ae69a37c4bdd0e08a8b0f7e123f6e403e774eb/appengine/components/components/protoutil/field_masks.py#7 |
| // In particular, if the client needs only some output properties, they |
| // can be requested with paths "output.properties.fields.foo". |
| google.protobuf.FieldMask fields = 100; |
| } |
| |
| // A request message for SearchBuilds rpc. |
| message SearchBuildsRequest { |
| // Returned builds must satisfy this predicate. Required. |
| BuildPredicate predicate = 1; |
| |
| // Fields to include in the response, see GetBuildRequest.fields. |
| // Note that this applies to the response, not each build, so e.g. steps must |
| // be requested with a path "builds.*.steps". |
| google.protobuf.FieldMask fields = 100; |
| |
| // Number of builds to return. |
| // Defaults to 100. |
| // Any value >1000 is interpreted as 1000. |
| int32 page_size = 101; |
| |
| // Value of SearchBuildsResponse.next_page_token from the previous response. |
| // Use it to continue searching. |
| string page_token = 102; |
| } |
| |
| // A response message for SearchBuilds rpc. |
| message SearchBuildsResponse { |
| // Search results. |
| // |
| // Ordered by build id, descending. Ids are monotonically decreasing, so in |
| // other words the order is newest-to-oldest. |
| repeated Build builds = 1; |
| |
| // Value for SearchBuildsRequest.page_token to continue searching. |
| string next_page_token = 100; |
| } |
| |
| // A request message for Batch rpc. |
| message BatchRequest { |
| |
| // One request in a batch. |
| message Request { |
| oneof request { |
| // GetBuild request. |
| GetBuildRequest get_build = 1; |
| // SearchBuilds request. |
| SearchBuildsRequest search_builds = 2; |
| // ScheduleBuild request. |
| // |
| // All ScheduleBuild requests in the batch are executed before other |
| // requests. |
| ScheduleBuildRequest schedule_build = 3; |
| } |
| } |
| |
| // Requests to execute in a single batch. |
| // |
| // All requests are executed in their own individual transactions. |
| // BatchRequest as a whole is not transactional. |
| // Mutations are executed before read-only requests. |
| repeated Request requests = 1; |
| } |
| |
| // A response message for Batch rpc. |
| message BatchResponse { |
| |
| // Response a BatchRequest.Response. |
| message Response { |
| oneof response { |
| // GetBuild response. |
| Build get_build = 1; |
| // SearchBuilds response. |
| SearchBuildsResponse search_builds = 2; |
| // ScheduleBuild response. |
| Build schedule_build = 3; |
| |
| // Error code and details of the unsuccessful RPC. |
| google.rpc.Status error = 100; |
| } |
| } |
| |
| // Responses in the same order as BatchRequest.requests. |
| repeated Response responses = 1; |
| } |
| |
| // A request message for UpdateBuild rpc. |
| message UpdateBuildRequest { |
| // Build to update, with new field values. |
| Build build = 1; |
| |
| // Build fields to update. |
| // See also |
| // https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#fieldmask |
| // |
| // Currently supports only the following path strings: |
| // - build.steps |
| // - build.output.properties |
| google.protobuf.FieldMask update_mask = 2; |
| |
| // Fields to include in the response. See also GetBuildRequest.fields. |
| google.protobuf.FieldMask fields = 100; |
| } |
| |
| // A request message for ScheduleBuild rpc. |
| // |
| // Next ID: 13. |
| message ScheduleBuildRequest { |
| // Required. A unique string id used for detecting duplicate requests. |
| // Should be unique at least per requesting identity. |
| // Used to dedup build scheduling requests with same id within 1 min. |
| // If a build was successfully scheduled with the same request id in the past |
| // minute, the existing build will be returned. |
| string request_id = 1; |
| |
| // ID of a build to retry as is or altered. |
| // When specified, fields below default to the values in the template build. |
| int64 template_build_id = 2; |
| |
| // Value for Build.builder. See its comments. |
| // Required, unless template_build_id is specified. |
| BuilderID builder = 3; |
| |
| // If specified, overrides server-defined value of |
| // Build.infra.buildbucket.canary. |
| // Otherwise the value is computed based on the builder config. |
| // See Swarming.task_template_canary_percentage in |
| // ./config/project_config.proto. |
| Trinary canary = 4; |
| |
| // If specified, overrides server-defined value of Build.input.experimental. |
| // Otherwise the value is computed based on the builder config. |
| // See Builder.experimental in ./config/project_config.proto. |
| Trinary experimental = 5; |
| |
| // Properties to include in Build.input.properties. |
| // |
| // Input properties of the created build are result of merging server-defined |
| // properties and properties in this field. |
| // Each property in this field defines a new or replaces an existing property |
| // on the server. |
| // If the server config does not allow overriding/adding the property, the |
| // request will fail with InvalidArgument error code. |
| // A server-defined property cannot be removed, but its value can be |
| // replaced with null. |
| // |
| // Reserved property paths: |
| // * ["buildbucket"] |
| // * ["buildername"] |
| // * ["blamelist""] |
| // * ["$recipe_engine/runtime", "is_luci"] |
| // * ["$recipe_engine/runtime", "is_experimental"] |
| // |
| // V1 equivalent: corresponds to "properties" key in "parameters_json". |
| google.protobuf.Struct properties = 6; |
| |
| // Value for Build.input.gitiles_commit. |
| // |
| // V1 equivalent: supersedes "revision" property and "buildset" |
| // tag that starts with "commit/gitiles/". |
| GitilesCommit gitiles_commit = 7; |
| |
| // Value for Build.input.gerrit_changes. |
| // 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 = 8; |
| |
| // Tags to include in Build.tags of the created build, see Build.tags |
| // comments. |
| // Note: tags of the created build may include other tags defined on the |
| // server. |
| repeated StringPair tags = 9; |
| |
| // Overrides default dimensions defined by builder config or template build. |
| // |
| // A set of entries with the same key defines a new or replaces an existing |
| // dimension with the same key. |
| // If the config does not allow overriding/adding the dimension, the request |
| // will fail with InvalidArgument error code. |
| // |
| // After merging, dimensions with empty value will be excluded. |
| repeated StringPair dimensions = 10; |
| |
| // If not zero, overrides swarming task priority. |
| // See also Build.infra.swarming.priority. |
| int32 priority = 11; |
| |
| // A per-build notification configuration. |
| NotificationConfig notify = 12; |
| |
| // Fields to include in the response. See also GetBuildRequest.fields. |
| google.protobuf.FieldMask fields = 100; |
| } |
| |
| // A request message for CancelBuild rpc. |
| message CancelBuildRequest { |
| // ID of the build to cancel. |
| int64 id = 1; |
| |
| // Required. Why the build is being cancelled. |
| CancelReason reason = 2; |
| |
| // Fields to include in the response. See also GetBuildRequest.fields. |
| google.protobuf.FieldMask fields = 100; |
| } |
| |
| // A build predicate. |
| // |
| // At least one of the following fields is required: builder, gerrit_changes and |
| // git_commits.. |
| // If a field value is empty, it is ignored, unless stated otherwise. |
| message BuildPredicate { |
| // A build must be in this builder. |
| BuilderID builder = 1; |
| |
| // A build must have this status. |
| Status status = 2; |
| |
| // A build's Build.Input.gerrit_changes must include ALL of these changes. |
| repeated GerritChange gerrit_changes = 3; |
| |
| // A build's Build.Output.gitiles_commit must match this commit. |
| // One of the following subfield sets must specified: |
| // - host, project, id |
| // - host, project, ref |
| // - host, project, ref, position |
| GitilesCommit output_gitiles_commit = 4; |
| |
| // A build must be created by this identity. |
| string created_by = 5; |
| |
| // A build must have ALL of these tags. |
| // For "ANY of these tags" make separate RPCs. |
| repeated StringPair tags = 6; |
| |
| // A build must have been created within the specified range. |
| // Both boundaries are optional. |
| TimeRange create_time = 7; |
| |
| // If false (default), a build must be non-experimental. |
| // Otherwise it may be experimental or non-experimental. |
| bool include_experimental = 8; |
| |
| // A build must be in this build range. |
| // A pair of SearchBuildsRequest.predicate.build.end_build_id and |
| // SearchBuildsRequest.page_size=1 can be used to find the previous build. |
| BuildRange build = 9; |
| |
| // A build must have a matching value of Build.infra.buildbucket.canary. |
| Trinary canary = 10; |
| } |
| |
| // Half-open build range. |
| // The range is defined on the build order in the context. |
| // Usually the order is newest-to-oldest, so start_build_id is a newer |
| // build and end_build_id is an older build. |
| message BuildRange { |
| // Inclusive lower boundary. Optional. |
| int64 start_build_id = 1; |
| // Exclusive upper boundary. Optional. |
| int64 end_build_id = 2; |
| } |