cv/api/v0/tryjob.proto

// Copyright 2021 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 cv.v0;

option go_package = "go.chromium.org/luci/cv/api/v0;cvpb";

import "go.chromium.org/luci/buildbucket/proto/builder_common.proto";
import "go.chromium.org/luci/cv/api/config/v2/config.proto";

// Tryjob represents a Run's view of a Tryjob.
message Tryjob {
  // Status is a high level status of a Tryjob.
  enum Status {
    // STATUS_UNSPECIFIED is never used.
    STATUS_UNSPECIFIED = 0;

    // PENDING means Tryjob is being triggered by CV.
    //
    // *must* have no Result.
    PENDING = 1;
    // TRIGGERED means Tryjob was triggered.
    //
    // *may* have been triggered by not CV but another user, service, etc.
    // *may* have a Result, which *may* still change.
    TRIGGERED = 2;
    // ENDED is a completed Tryjob. Final status.
    //
    // *must* have a Result, whose Status is not UNKNOWN.
    ENDED = 3;
    // CANCELLED is Tryjob cancelled by CV. Final status.
    //
    // *must* have no Result.
    CANCELLED = 4;
    // UNTRIGGERED means Tryjob was not triggered. Final status.
    //
    // *must* have no Result.
    UNTRIGGERED = 5;
  }

  // Result of a Tryjob.
  message Result {
    // Status of the Result.
    //
    // This is the verdict of verification of Run's CLs by this Tryjob.
    Status status = 1;

    enum Status {
      // RESULT_STATUS_UNSPECIFIED is never used.
      RESULT_STATUS_UNSPECIFIED = 0;
      // UNKNOWN means Tryjob didn't reach a conclusion.
      UNKNOWN = 1;
      // SUCCEEDED means that Run's CLs are considered OK by this Tryjob.
      SUCCEEDED = 2;
      // FAILED_PERMANENTLY means that Run's CLs are most likely not good.
      FAILED_PERMANENTLY = 3;
      // FAILED_TRANSIENTLY means that Run's CLs are most likely not to blame
      // for the failure.
      // TODO(crbug/1227363): consider removing transiency aspect if possible.
      FAILED_TRANSIENTLY = 4;
      // TIMEOUT means the Tryjob ran over some deadline and did not make a
      // decision about this Run's CLs.
      TIMEOUT = 5;
    }

    // Backend houses backend-specific output.
    oneof backend {
      Buildbucket buildbucket = 5;
    }

    message Buildbucket {
      int64 id = 1;
      reserved 2; // status
    }
  }

  reserved 1; // definition

  // Status of the Tryjob.
  Status status = 2;

  // Result of the Tryjob.
  Result result = 3;

  // Indicates whether this Tryjob is considered critical to a Run's final
  // status. If true, failure of this Tryjob will fail the Run immediately.
  // Run is considered SUCCEEDED iff all critical Tryjobs have passed.
  //
  // As of Mar. 2022, a Tryjob is considered critical if it is not experimental
  // or it is triggered directly by `Cq-Include-Trybots` footer.
  bool critical = 4;

  // Indicates whether a Run is reusing this Tryjob rather than triggering
  // its own Tryjob. A Run may reuse Tryjobs triggered by some previous Runs or
  // maually by users as long as CV sees fit.
  bool reuse = 5;
}

// TryjobStatus is the status of a tryjob.
enum TryjobStatus {
  // STATUS_UNSPECIFIED is never used.
  TRYJOB_STATUS_UNSPECIFIED = 0;
  // PENDING means tryjob is being triggered by CV.
  PENDING = 1;
  // RUNNING means tryjob is currently running.
  //
  // This status is from CV's PoV. As soon as LUCI CV successfully launches
  // the tryjob against the backend, it's considered running. However, it's
  // still possible the tryjob is pending the backend system (for example,
  // waiting for the swarming bot).
  RUNNING = 2;
  // SUCCEEDED means that run's CL(s) are considered OK by this tryjob.
  SUCCEEDED = 3;
  // FAILED means that run's CL(s) are considered NOT OK by this tryjob.
  FAILED = 4;
  // CANCELLED means the tryjob gets cancelled by LUCI CV.
  //
  // Note that, this only counts the cancellation initiated by LUCI CV. If
  // user requested cancelling a build through Buildbucket UI for example, the
  // status would be FAILED instead.
  CANCELLED = 5;
  // UNTRIGGERED means the tryjob was not triggered.
  //
  // Possible reasons includes getting permission denied from Buildbucket,
  // Buildbucket is temporarily down.
  UNTRIGGERED = 6;
}

// TryjobResult is the result of a tryjob.
message TryjobResult {
  // Backend houses backend-specific output.
  oneof backend {
    Buildbucket buildbucket = 1;
  }

  message Buildbucket {
    // Buildbucket host.
    string host = 1;
    // ID of the build.
    int64 id = 2;
    // Buildbucket builder.
    buildbucket.v2.BuilderID builder = 3;
  }
}

message TryjobInvocation {
  // Attempt represents an attempt to invoke the tryjob.
  message Attempt {
    // Status is the status of this tryjob attempt at the time the run ends.
    TryjobStatus status = 1;
    // Result is the result of this tryjob attempt at the time the run ends.
    //
    // It's possible that result is empty. For example, the run ends even before
    // LUCI CV launches any tryjob.
    TryjobResult result = 2;
    // Indicates whether this attempt is a reuse of previously triggered tryjob
    // rather than launching its own tryjob.
    bool reuse = 3;
  }

  // Config is the configuration of the tryjob defined in the project config.
  cv.config.Verifiers.Tryjob.Builder builder_config = 1;
  // Final status of this tryjob invocation at the time run ends.
  //
  // This should be the status of the latest attempt (i.e. first element in
  // `attempts` field).
  TryjobStatus status = 2;
  // Indicates whether this tryjob invocation is considered critical to a run's
  // final status. If true, failure of this tryjob invocation will fail the run
  // immediately. Run is considered SUCCEEDED iff all critical tryjobs have
  // passed.
  //
  // As of Dec 2023, a tryjob invocation is considered critical if it is not
  // experimental or it is triggered directly by `Cq-Include-Trybots` footer.
  bool critical = 3;
  // Attempts are all attempts for this tryjob invocation.
  //
  // Sorted from the latest attempt made to the earliest attempt made.
  // Must contain at least one element.
  repeated Attempt attempts = 4;
}