blob: 8f72dc6ba2e3135b29beb70147ddf7ac1adcae57 [file] [log] [blame]
// 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/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
// Status of a build or a step.
enum Status {
// Unspecified state. Meaning depends on the context.
STATUS_UNSPECIFIED = 0;
// Build was scheduled, but did not start or end yet.
SCHEDULED = 1;
// Build/step has started.
STARTED = 2;
// A union of all terminal statuses.
// Can be used in BuildPredicate.status.
// A concrete build/step cannot have this status.
// Can be used as a bitmask to check that a build/step ended.
ENDED_MASK = 4;
// A build/step ended successfully.
// This is a terminal status. It may not transition to another status.
SUCCESS = 12; // 8 | ENDED
// A build/step ended unsuccessfully due to its Build.Input,
// e.g. tests failed, and NOT due to a build infrastructure failure.
// This is a terminal status. It may not transition to another status.
FAILURE = 20; // 16 | ENDED
// A build/step ended unsuccessfully due to a failure independent of the
// input, e.g. swarming failed, not enough capacity or the recipe was unable
// to read the patch from gerrit.
// start_time is not required for this status.
// This is a terminal status. It may not transition to another status.
INFRA_FAILURE = 36; // 32 | ENDED
// A build was cancelled explicitly, e.g. via an RPC.
// This is a terminal status. It may not transition to another status.
CANCELED = 68; // 64 | ENDED
}
// An executable to run when the build is ready to start.
//
// The following describes the protocol between buildbucket and the executable.
// The executable MUST NOT assume/rely on anything that is not explicitly
// specified below.
//
// The executable will be started with the following input:
// - empty current working directory (CWD).
// - stdin: binary-encoded buildbucket.v2.Build message.
// - $TMPDIR, $TEMP, $TMP: env variables point to an empty directory, on the
// same file system as CWD.
// - $LOGDOG_COORDINATOR_HOST, $LOGDOG_STREAM_PROJECT, $LOGDOG_STREAM_PREFIX,
// $LOGDOG_NAMESPACE, $LOGDOG_STREAM_SERVER_PATH: env variables describing
// LogDog context, part of the LogDog Butler protocol.
// The executable MAY create logdog streams using these variables.
// Read more at https://godoc.org/go.chromium.org/luci/logdog/client/butlerlib/bootstrap
// - LUCI_CONTEXT["run_build"]["cache_dir"]: a LUCI context value pointing to
// the root directory of Swarming named caches.
// MAY be on the same file system as CWD.
// For example, builder cache is available at "<cache_dir>/builder".
// For LUCI Context doc, see
// https://chromium.googlesource.com/infra/luci/luci-py/+/HEAD/client/LUCI_CONTEXT.md
// See also CacheEntry.
//
// The executable MUST write "$LOGDOG_NAMESPACE/build.proto" stream using the
// LogDog streamserver at $LOGDOG_STREAM_SERVER_PATH.
// The stream MUST have a binary-encoded buildbucket.v2.Build message datagrams,
// with content type "application/luci+proto; message=buildbucket.v2.Build".
// Server-side build will be updated with the values from the latest message.
//
// A build step S without children in the datagram MAY have a Step.Log named
// "$build.proto".
// It MUST point to a LogDog datagram stream with binary-encoded
// buildbucket.v2.Build messages and content type
// "application/luci+proto; message=buildbucket.v2.Build".
// The step tree from the second datagram will appear as substeps of step S.
// This rule applies recursively, i.e. a leaf step in the datagram MAY also
// have a "$build.proto" log.
// The graph of datagram streams MUST be a tree, i.e. acyclic.
//
// All build step log urls of all Build messages MUST be relative to
// $LOGDOG_STREAM_PREFIX (only stream name) and start with $LOGDOG_NAMESPACE.
message Executable {
// The CIPD package containing the executable.
// On Linux/Mac, the executable MUST be named "run_build".
// On Windows, it MUST be named "run_build.exe" or "run_build.bat",
// in this order of precedence.
string cipd_package = 1;
// The CIPD version to fetch. Defaults to `latest`.
string cipd_version = 2;
}
// Machine-readable details of a status.
// Human-readble details are present in a sibling summary_markdown field.
message StatusDetails {
reserved 1; // is_resource_exhaustion, replaced by resource_exhaustion
reserved 2; // is_timeout, replaced with timeout.
message ResourceExhaustion {}
// If set, indicates that the failure was due to a resource exhaustion / quota
// denial.
// Applicable in FAILURE and INFRA_FAILURE statuses.
ResourceExhaustion resource_exhaustion = 3;
message Timeout {}
// If set, indicates that the failure was due to a timeout.
// Applicable in FAILURE and INFRA_FAILURE statuses.
Timeout timeout = 4;
}
// A Gerrit patchset.
message GerritChange {
// Gerrit hostname, e.g. "chromium-review.googlesource.com".
string host = 1;
// Gerrit project, e.g. "chromium/src".
string project = 2;
// Change number, e.g. 12345.
int64 change = 3;
// Patch set number, e.g. 1.
int64 patchset = 4;
}
// A landed Git commit hosted on Gitiles.
message GitilesCommit {
// Gitiles hostname, e.g. "chromium.googlesource.com".
string host = 1;
// Repository name on the host, e.g. "chromium/src".
string project = 2;
// Commit HEX SHA1.
string id = 3;
// Commit ref, e.g. "refs/heads/master".
// NOT a branch name: if specified, must start with "refs/".
string ref = 4;
// Defines a total order of commits on the ref. Requires ref field.
// Typically 1-based, monotonically increasing, contiguous integer
// defined by a Gerrit plugin, goto.google.com/git-numberer.
// TODO(tandrii): make it a public doc.
uint32 position = 5;
}
// A key-value pair of strings.
message StringPair {
string key = 1;
string value = 2;
}
// Half-open time range.
message TimeRange {
// Inclusive lower boundary. Optional.
google.protobuf.Timestamp start_time = 1;
// Exclusive upper boundary. Optional.
google.protobuf.Timestamp end_time = 2;
}
// A boolean with an undefined value.
enum Trinary {
UNSET = 0;
YES = 1;
NO = 2;
}
// A requested dimension. Looks like StringPair, but also has an expiration.
message RequestedDimension {
string key = 1;
string value = 2;
// If set, ignore this dimension after this duraiton.
google.protobuf.Duration expiration = 3;
}