buildbucket/proto/step.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/timestamp.proto";
import "go.chromium.org/luci/buildbucket/proto/common.proto";

// A build step.
//
// A step may have children, see name field.
message Step {
  // Name of the step, unique within the build.
  // Identifies the step.
  //
  // Pipe character ("|") is reserved to separate parent and child step names.
  // For example, value "a|b" indicates step "b" under step "a".
  // If this is a child step, a parent MUST exist and MUST precede this step in
  // the list of steps.
  // All step names, including child and parent names recursively,
  // MUST NOT be an empty string.
  // For example, all of the below names are invalid.
  // - |a
  // - a|
  // - a||b
  string name = 1;

  // The timestamp when the step started.
  //
  // MUST NOT be specified, if status is SCHEDULED.
  // MUST be specified, if status is STARTED, SUCCESS, FAILURE, or INFRA_FAILURE
  // MAY be specified, if status is CANCELED.
  google.protobuf.Timestamp start_time = 2;

  // The timestamp when the step ended.
  // Present iff status is terminal.
  // MUST NOT be before start_time.
  google.protobuf.Timestamp end_time = 3;

  // Status of the step.
  // Must be specified, i.e. not STATUS_UNSPECIFIED.
  Status status = 4;

  // Logs produced by the step.
  // Log order is up to the step.
  //
  // BigQuery: excluded from rows.
  repeated Log logs = 5;

  message MergeBuild {
    // If set, then this stream is expected to be a datagram stream
    // containing Build messages.
    //
    // This should be the stream name relative to the current build's
    // $LOGDOG_NAMESPACE.
    string from_logdog_stream = 1;

    // If set, then this stream will be merged "in line" with this step.
    //
    // Properties emitted by the merge build stream will overwrite global
    // outputs with the same top-level key.
    //
    // Steps emitted by the merge build stream will NOT have their names
    // namespaced (though the log stream names are still expected to
    // adhere to the regular luciexe rules).
    //
    // Because this is a legacy feature, this intentionally omits other fields
    // which "could be" merged, because there was no affordance to emit them
    // under the legacy annotator scheme:
    //   * output.gitiles_commit will not be merged.
    //   * output.logs will not be merged.
    //   * summary_markdown will not be merged.
    //
    // This is NOT a recommended mode of operation, but legacy ChromeOS
    // builders rely on this behavior.
    //
    // See crbug.com/1310155.
    bool legacy_global_namespace = 2;
  }
  // MergeBuild is used for go.chromium.org/luci/luciexe to indicate to the
  // luciexe host process if some Build stream should be merged under this step.
  //
  // BigQuery: excluded from rows.
  MergeBuild merge_build = 6;

  // Human-readable summary of the step provided by the step itself,
  // in Markdown format (https://spec.commonmark.org/0.28/).
  //
  // V1 equivalent: combines and supersedes Buildbot's step_text and step links and also supports
  // other formatted text.
  //
  // BigQuery: excluded from rows.
  string summary_markdown = 7;

  // Arbitrary annotations for the step.
  //
  // One key may have multiple values, which is why this is not a map<string,string>.
  //
  // These are NOT interpreted by Buildbucket.
  //
  // Tag keys SHOULD indicate the domain/system that interprets them, e.g.:
  //
  //   my_service.category = COMPILE
  //
  // Rather than
  //
  //   is_compile = true
  //
  // This will help contextualize the tag values when looking at a build (who
  // set this tag? who will interpret this tag?))
  //
  // The 'luci.' key prefix is reserved for LUCI's own usage.
  //
  // The Key may not exceed 256 bytes.
  // The Value may not exceed 1024 bytes.
  //
  // Key and Value may not be empty.
  repeated StringPair tags = 8;
}