buildbucket/proto/build.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";
import "google/protobuf/struct.proto";
import "go.chromium.org/luci/buildbucket/proto/builder.proto";
import "go.chromium.org/luci/buildbucket/proto/common.proto";
import "go.chromium.org/luci/buildbucket/proto/step.proto";
import "go.chromium.org/luci/swarming/proto/api/swarming.proto";

// A single build, identified by an int64 id.
// Belongs to a builder.
//
// RPC: see Builds service for build creation and retrieval.
// Some Build fields are marked as excluded from responses by default.
// Use build_fields request field to specify that a field must be included.
//
// BigQuery: this message also defines schema of a BigQuery table of completed builds.
// A BigQuery row is inserted soon after build ends, i.e. a row represents a state of
// a build at completion time and does not change after that.
// All fields are included.
//
// Next id: 30.
message Build {
  // Defines what to build/test.
  //
  // Behavior of a build executable MAY depend on Input.
  // It MAY NOT modify its behavior based on anything outside of Input.
  // It MAY read non-Input fields to display for debugging or to pass-through to
  // triggered builds. For example the "tags" field may be passed to triggered
  // builds, or the "infra" field may be printed for debugging purposes.
  message Input {
    // Arbitrary JSON object. Available at build run time.
    //
    // RPC: By default, this field is excluded from responses.
    //
    // V1 equivalent: corresponds to "properties" key in "parameters_json".
    google.protobuf.Struct properties = 1;

    // The Gitiles commit to run against.
    // Usually present in CI builds, set by LUCI Scheduler.
    // If not present, the build may checkout "refs/heads/master".
    // NOT a blamelist.
    //
    // V1 equivalent: supersedes "revision" property and "buildset"
    // tag that starts with "commit/gitiles/".
    GitilesCommit gitiles_commit = 2;

    // Gerrit patchsets to run against.
    // 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 = 3;

    // DEPRECATED
    //
    // Equivalent to `"luci.non_production" in experiments`.
    //
    // See `Builder.experiments` for well-known experiments.
    bool experimental = 5;

    // The sorted list of experiments enabled on this build.
    //
    // See `Builder.experiments` for well-known experiments.
    repeated string experiments = 6;
  }

  // Result of the build executable.
  message Output {
    reserved 2; // summary_markdown, was moved to Build.
    reserved 4; // critical, was moved to Build.

    // Arbitrary JSON object produced by the build.
    //
    // In recipes, use step_result.presentation.properties to set these,
    // for example
    //
    //   step_result = api.step(['echo'])
    //   step_result.presentation.properties['foo'] = 'bar'
    //
    // More docs: https://chromium.googlesource.com/infra/luci/recipes-py/+/HEAD/doc/old_user_guide.md#Setting-properties
    //
    // V1 equivalent: corresponds to "properties" key in
    // "result_details_json".
    // In V1 output properties are not populated until build ends.
    google.protobuf.Struct properties = 1;

    // Build checked out and executed on this commit.
    //
    // Should correspond to Build.Input.gitiles_commit.
    // May be present even if Build.Input.gitiles_commit is not set, for example
    // in cron builders.
    //
    // V1 equivalent: this supersedes all got_revision output property.
    GitilesCommit gitiles_commit = 3;

    // Logs produced by the build script, typically "stdout" and "stderr".
    repeated Log logs = 5;
  }

  reserved 5; // view_url
  reserved 13; // infra_failure_reason was moved into status_details.
  reserved 14; // cancel_reason was moved into status_details.

  // Identifier of the build, unique per LUCI deployment.
  // IDs are monotonically decreasing.
  int64 id = 1;

  // Required. The builder this build belongs to.
  //
  // Tuple (builder.project, builder.bucket) defines build ACL
  // which may change after build has ended.
  BuilderID builder = 2;

  // Human-readable identifier of the build with the following properties:
  // - unique within the builder
  // - a monotonically increasing number
  // - mostly contiguous
  // - much shorter than id
  //
  // Caution: populated (positive number) iff build numbers were enabled
  // in the builder configuration at the time of build creation.
  //
  // Caution: Build numbers are not guaranteed to be contiguous.
  // There may be gaps during outages.
  //
  // Caution: Build numbers, while monotonically increasing, do not
  // necessarily reflect source-code order. For example, force builds
  // or rebuilds can allocate new, higher, numbers, but build an older-
  // than-HEAD version of the source.
  int32 number = 3;

  // Verified LUCI identity that created this build.
  string created_by = 4;

  // Verified LUCI identity that canceled this build.
  string canceled_by = 23;

  // When the build was created.
  google.protobuf.Timestamp create_time = 6;
  // When the build started.
  // Required iff status is STARTED, SUCCESS or FAILURE.
  google.protobuf.Timestamp start_time = 7;
  // When the build ended.
  // Present iff status is terminal.
  // MUST NOT be before start_time.
  google.protobuf.Timestamp end_time = 8;
  // When the build was most recently updated.
  //
  // RPC: can be > end_time if, e.g. new tags were attached to a completed
  // build.
  google.protobuf.Timestamp update_time = 9;

  // Status of the build.
  // Must be specified, i.e. not STATUS_UNSPECIFIED.
  //
  // RPC: Responses have most current status.
  //
  // BigQuery: Final status of the build. Cannot be SCHEDULED or STARTED.
  Status status = 12;

  // Human-readable summary of the build in Markdown format
  // (https://spec.commonmark.org/0.28/).
  // Explains status.
  // Up to 4 KB.
  //
  // BigQuery: excluded from rows.
  string summary_markdown = 20;

  // If NO, then the build status SHOULD NOT be used to assess correctness of
  // the input gitiles_commit or gerrit_changes.
  // For example, if a pre-submit build has failed, CQ MAY still land the CL.
  // For example, if a post-submit build has failed, CLs MAY continue landing.
  Trinary critical = 21;

  // Machine-readable details of the current status.
  // Human-readable status reason is available in summary_markdown.
  StatusDetails status_details = 22;

  // Input to the build executable.
  Input input = 15;

  // Output of the build executable.
  // SHOULD depend only on input field and NOT other fields.
  // MUST be unset if build status is SCHEDULED.
  //
  // RPC: By default, this field is excluded from responses.
  // Updated while the build is running and finalized when the build ends.
  Output output = 16;

  // Current list of build steps.
  // Updated as build runs.
  //
  // May take up to 1MB after zlib compression.
  // MUST be unset if build status is SCHEDULED.
  //
  // RPC: By default, this field is excluded from responses.
  repeated Step steps = 17;

  // Build infrastructure used by the build.
  //
  // RPC: By default, this field is excluded from responses.
  BuildInfra infra = 18;

  // Arbitrary annotations for the build.
  // One key may have multiple values, which is why this is not a map<string,string>.
  // Indexed by the server, see also BuildPredicate.tags.
  repeated StringPair tags = 19;

  // What to run when the build is ready to start.
  Executable exe = 24;

  // DEPRECATED
  //
  // Equivalent to `"luci.buildbucket.canary_software" in input.experiments`.
  //
  // See `Builder.experiments` for well-known experiments.
  bool canary = 25;

  // Maximum build pending time.
  // If the timeout is reached, the build is marked as INFRA_FAILURE status
  // and both status_details.{timeout, resource_exhaustion} are set.
  google.protobuf.Duration scheduling_timeout = 26;

  // Maximum build execution time.
  //
  // Not to be confused with scheduling_timeout.
  //
  // If the timeout is reached, the task will be signaled according to the
  // `deadline` section of
  // https://chromium.googlesource.com/infra/luci/luci-py/+/HEAD/client/LUCI_CONTEXT.md
  // and status_details.timeout is set.
  //
  // The task will have `grace_period` amount of time to handle cleanup
  // before being forcefully terminated.
  google.protobuf.Duration execution_timeout = 27;

  // Amount of cleanup time after execution_timeout.
  //
  // After being signaled according to execution_timeout, the task will
  // have this duration to clean up before being forcefully terminated.
  //
  // The signalling process is explained in the `deadline` section of
  // https://chromium.googlesource.com/infra/luci/luci-py/+/HEAD/client/LUCI_CONTEXT.md.
  google.protobuf.Duration grace_period = 29;

  // If set, swarming was requested to wait until it sees at least one bot
  // report a superset of the build's requested dimensions.
  bool wait_for_capacity = 28;
}

// Build infrastructure that was used for a particular build.
message BuildInfra {

  // Buildbucket-specific information, captured at the build creation time.
  message Buildbucket {
    reserved 4; // field "canary" was moved to Build message.

    // Version of swarming task template. Defines
    // versions of kitchen, git, git wrapper, python, vpython, etc.
    string service_config_revision = 2;
    // Properties that were specified in ScheduleBuildRequest to create this
    // build.
    //
    // In particular, CQ uses this to decide whether the build created by
    // someone else is appropriate for CQ, e.g. it was created with the same
    // properties that CQ would use.
    google.protobuf.Struct requested_properties = 5;

    // Dimensions that were specified in ScheduleBuildRequest to create this
    // build.
    repeated RequestedDimension requested_dimensions = 6;

    // Buildbucket hostname, e.g. "cr-buildbucket.appspot.com".
    string hostname = 7;
  }

  // Swarming-specific information.
  //
  // Next ID: 10.
  message Swarming {
    // Describes a cache directory persisted on a bot.
    //
    // If a build requested a cache, the cache directory is available on build
    // startup. If the cache was present on the bot, the directory contains
    // files from the previous run on that bot.
    // The build can read/write to the cache directory while it runs.
    // After build completes, the cache directory is persisted.
    // The next time another build requests the same cache and runs on the same
    // bot, the files will still be there (unless the cache was evicted,
    // perhaps due to disk space reasons).
    //
    // One bot can keep multiple caches at the same time and one build can request
    // multiple different caches.
    // A cache is identified by its name and mapped to a path.
    //
    // If the bot is running out of space, caches are evicted in LRU manner
    // before the next build on this bot starts.
    //
    // Builder cache.
    //
    // Buildbucket implicitly declares cache
    //   {"name": "<hash(project/bucket/builder)>", "path": "builder"}.
    // This means that any LUCI builder has a "personal disk space" on the bot.
    // Builder cache is often a good start before customizing caching.
    // In recipes, it is available at api.buildbucket.builder_cache_path.
    //
    message CacheEntry {
      // Identifier of the cache. Required. Length is limited to 128.
      // Must be unique in the build.
      //
      // If the pool of swarming bots is shared among multiple LUCI projects and
      // projects use same cache name, the cache will be shared across projects.
      // To avoid affecting and being affected by other projects, prefix the
      // cache name with something project-specific, e.g. "v8-".
      string name = 1;

      // Relative path where the cache in mapped into. Required.
      //
      // Must use POSIX format (forward slashes).
      // In most cases, it does not need slashes at all.
      //
      // In recipes, use api.path['cache'].join(path) to get absolute path.
      //
      // Must be unique in the build.
      string path = 2;

      // Duration to wait for a bot with a warm cache to pick up the
      // task, before falling back to a bot with a cold (non-existent) cache.
      //
      // The default is 0, which means that no preference will be chosen for a
      // bot with this or without this cache, and a bot without this cache may
      // be chosen instead.
      //
      // If no bot has this cache warm, the task will skip this wait and will
      // immediately fallback to a cold cache request.
      //
      // The value must be multiples of 60 seconds.
      google.protobuf.Duration wait_for_warm_cache = 3;

      // Environment variable with this name will be set to the path to the cache
      // directory.
      string env_var = 4;
    }

    // Swarming hostname, e.g. "chromium-swarm.appspot.com".
    // Populated at the build creation time.
    string hostname = 1;

    // Swarming task id.
    // Not guaranteed to be populated at the build creation time.
    string task_id = 2;

    // Swarming run id of the parent task from which this build is triggered.
    // If set, swarming promises to ensure this build won't outlive its parent
    // swarming task (which may or may not itself be a Buildbucket build).
    // Populated at the build creation time.
    string parent_run_id = 9;

    // Task service account email address.
    // This is the service account used for all authenticated requests by the
    // build.
    string task_service_account = 3;

    // Priority of the task. The lower the more important.
    // Valid values are [20..255].
    int32 priority = 4;

    // Swarming dimensions for the task.
    repeated RequestedDimension task_dimensions = 5;

    // Swarming dimensions of the bot used for the task.
    repeated StringPair bot_dimensions = 6;

    // Caches requested by this build.
    repeated CacheEntry caches = 7;

    // Swarming task containment for the task.
    swarming.v1.Containment containment = 8;
  }

  // LogDog-specific information.
  message LogDog {
    // LogDog hostname, e.g. "logs.chromium.org".
    string hostname = 1;

    // LogDog project, e.g. "chromium".
    // Typically matches Build.builder.project.
    string project = 2;

    // A slash-separated path prefix shared by all logs and artifacts of this
    // build.
    // No other build can have the same prefix.
    // Can be used to discover logs and/or load log contents.
    //
    // Can be used to construct URL of a page that displays stdout/stderr of all
    // steps of a build. In pseudo-JS:
    //   q_stdout = `${project}/${prefix}/+/**/stdout`;
    //   q_stderr = `${project}/${prefix}/+/**/stderr`;
    //   url = `https://${host}/v/?s=${urlquote(q_stdout)}&s=${urlquote(q_stderr)}`;
    string prefix = 3;
  }

  // Recipe-specific information.
  message Recipe {
    // CIPD package name containing the recipe used to run this build.
    string cipd_package = 1;

    // Name of the recipe used to run this build.
    string name = 2;
  }

  // ResultDB-specific information.
  message ResultDB {
    // Hostname of the ResultDB instance, such as "results.api.cr.dev".
    string hostname = 1;

    // Name of the invocation for results of this build.
    // Typically "invocations/build:<build_id>".
    string invocation = 2;
  }

  Buildbucket buildbucket = 1;
  Swarming swarming = 2;
  LogDog logdog = 3;
  Recipe recipe = 4;
  ResultDB resultdb = 5;
}