blob: 076b46300d20786183dfef68ae70e73e9c1fc511 [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.
//
// Please refer to go.chromium.org/luci/luciexe for the protocol this executable
// is expected to implement.
//
// In addition to the "Host Application" responsibilities listed there,
// buildbucket will also ensure that $CWD points to an empty directory when it
// starts the build.
message Executable {
// The CIPD package containing the executable.
//
// See the `cmd` field below for how the executable will be located within the
// package.
string cipd_package = 1;
// The CIPD version to fetch.
//
// Optional. If omitted, this defaults to `latest`.
string cipd_version = 2;
// The command to invoke within the package.
//
// The 0th argument is taken as relative to the cipd_package root (a.k.a.
// BBAgentArgs.payload_path), so "foo" would invoke the binary called "foo" in
// the root of the package. On Windows, this will automatically look
// first for ".exe" and ".bat" variants. Similarly, "subdir/foo" would
// look for "foo" in "subdir" of the CIPD package.
//
// The other arguments are passed verbatim to the executable.
//
// The 'build.proto' binary message will always be passed to stdin, even when
// this command has arguments (see go.chromium.org/luci/luciexe).
//
// RECOMMENDATION: It's advised to rely on the build.proto's Input.Properties
// field for passing task-specific data. Properties are JSON-typed and can be
// modeled with a protobuf (using JSONPB). However, supplying additional args
// can be useful to, e.g., increase logging verbosity, or similar
// 'system level' settings within the binary.
//
// Optional. If omitted, defaults to `['luciexe']`.
repeated string cmd = 3;
// Wrapper is a command and its args which will be used to 'wrap' the
// execution of `cmd`.
// Given:
// wrapper = ['/some/exe', '--arg']
// cmd = ['my_exe', '--other-arg']
// Buildbucket's agent will invoke
// /some/exe --arg -- /path/to/task/root/dir/my_exe --other-arg
// Note that '--' is always inserted between the wrapper and the target
// cmd
//
// The wrapper program MUST maintain all the invariants specified in
// go.chromium.org/luci/luciexe (likely by passing-through
// most of this responsibility to `cmd`).
//
// wrapper[0] MAY be an absolute path. If https://pkg.go.dev/path/filepath#IsAbs
// returns `true` for wrapper[0], it will be interpreted as an absolute
// path. In this case, it is your responsibility to ensure that the target
// binary is correctly deployed an any machine where the Build might run
// (by whatever means you use to prepare/adjust your system image). Failure to do
// so will cause the build to terminate with INFRA_FAILURE.
//
// If wrapper[0] is non-absolute, but does not contain a path separator,
// it will be looked for in $PATH (and the same rules apply for
// pre-distribution as in the absolute path case).
//
// If wrapper[0] begins with a "./" (or ".\") or contains a path separator
// anywhere, it will be considered relative to the task root.
//
// Example wrapper[0]:
//
// Absolute path (*nix): /some/prog
// Absolute path (Windows): C:\some\prog.exe
// $PATH or %PATH% lookup: prog
// task-relative (*nix): ./prog ($taskRoot/prog)
// task-relative (*nix): dir/prog ($taskRoot/dir/prog)
// task-relative (Windows): .\prog.exe ($taskRoot\\prog.exe)
// task-relative (Windows): dir\prog.exe ($taskRoot\\dir\\prog.exe)
repeated string wrapper = 4;
}
// 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 build ended due to the expiration_timeout or
// scheduling_timeout set for the build.
//
// Applicable in all final statuses.
//
// SUCCESS+timeout would indicate a successful recovery from a timeout signal
// during the build's grace_period.
Timeout timeout = 4;
}
// A named log of a step or build.
message Log {
// Log name, standard ("stdout", "stderr") or custom (e.g. "json.output").
// Unique within the containing message (step or build).
string name = 1;
// URL of a Human-readable page that displays log contents.
string view_url = 2;
// URL of the log content.
// As of 2018-09-06, the only supported scheme is "logdog".
// Typically it has form
// "logdog://<host>/<project>/<prefix>/+/<stream_name>".
// See also
// https://godoc.org/go.chromium.org/luci/logdog/common/types#ParseURL
string url = 3;
}
// 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/".
// If id is set, ref SHOULD also be set, so that git clients can
// know how to obtain the commit by id.
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 duration.
google.protobuf.Duration expiration = 3;
}