buildbucket/proto/common.proto

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

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