blob: e21392af78ce187edc3645bd467210023ae791d5 [file] [log] [blame]
// 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 {
GetBuildRequest get_build = 1;
SearchBuildsRequest search_builds = 2;
// All ScheduleBuild requests in the batch are executed before other
// requests.
ScheduleBuildRequest schedule_build = 3;
CancelBuildRequest cancel_build = 4 ;
}
}
// 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 {
Build get_build = 1;
SearchBuildsResponse search_builds = 2;
Build schedule_build = 3;
Build cancel_build = 4;
// 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: 14.
message ScheduleBuildRequest {
// ** STRONGLY RECOMMENDED **.
// 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.
//
// Setting this field will cause the created build to have a "buildset"
// tag with value "commit/gitiles/{hostname}/{project}/+/{id}".
//
// GitilesCommit objects MUST have host, project, ref fields set.
//
// 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.
// All GerritChange fields are required.
//
// Setting this field will cause the created build to have a "buildset"
// tag with value "patch/gerrit/{hostname}/{change}/{patchset}"
// for each change.
//
// 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.
//
// A dimension expiration must be a multiple of 1min.
repeated RequestedDimension 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;
// Value for Build.critical.
Trinary critical = 13;
}
// A request message for CancelBuild rpc.
message CancelBuildRequest {
// ID of the build to cancel.
int64 id = 1;
// Required. Value for Build.summary_markdown.
string summary_markdown = 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;
}