go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/cv/api/recipe/v1/cq.proto

// Copyright 2019 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 cq.recipe;

option go_package = "go.chromium.org/luci/cv/api/recipe/v1;recipe";

// Input provides CQ metadata for CQ-triggered tryjob.
message Input {
  // If true, CQ is active for the current build. CQ is considered "active" for
  // a build if CQ triggered the build, either directly or indirectly.
  bool active = 1;

  // If false, CQ would try to submit CL(s) if all other checks pass.
  // If true, CQ won't try to submit.
  //
  // DEPRECATED: Use run_mode instead.
  bool dry_run = 2;

  // If true, CQ will not take this build into account while deciding whether
  // CL is good or not. See also `experiment_percentage` of CQ's config file.
  bool experimental = 3;

  // If true, CQ triggered this build directly, otherwise typically indicates a
  // child build triggered by a CQ triggered one (possibly indirectly).
  //
  // Can be spoofed. *DO NOT USE FOR SECURITY CHECKS.*
  //
  // One possible use is to distinguish which builds must be cancelled manually,
  // and which (top_level=True) CQ would cancel itself.
  bool top_level = 4;

  // The mode of the CQ Run that triggers this Tryjob.
  string run_mode = 5;

  // Tells whether the Run owner is a Googler.
  //
  // DO NOT USE: This is a temporary workaround for crbug/1259887 which
  // is supposed to be used by Chromium only.
  // TODO(crbug/1382195): Remove this field after long term solution is
  // ready.
  bool owner_is_googler = 20;
}

// Output provides build-specific instructions back to CQ.
//
// Unless stated otherwise, each Output message field can be set even on builds
// not triggered directly or indirectly by CQ itself. For example, `git cl try`
// or Gerrit UI can be used to trigger a build directly, which can then instruct
// CQ not to retry it.
//
// CQ periodically checks the Output of still running builds, too,
// and may act on the Output even before a build is completed.
message Output {

  // Buildbucket build IDs which this build has triggered for CQ to wait on.
  //
  // Required when using triggered_by builders in project's CQ config.
  // This is useful to allow the triggering builder to finish without waiting
  // for its child builds, which can be efficiently done by CQ.
  //
  // This is equivalent to setting legacy top-level "triggered_build_ids" output
  // property.
  // TODO(tandrii): deprecate and remove the legacy property.
  repeated int64 triggered_build_ids = 1;

  enum Retry {
    OUTPUT_RETRY_UNSPECIFIED = 0;
    // Default. Allow CQ to retry the build.
    //
    // Does NOT force CQ to retry this build, since it depends on other factors,
    // such as the applicable project's CQ config.
    OUTPUT_RETRY_ALLOWED = 1;
    // Denies retries regardless of other factors.
    //
    // This is equivalent to setting legacy top-level `"do_not_retry": true`
    // output property.
    // TODO(tandrii): deprecate and remove the legacy property.
    OUTPUT_RETRY_DENIED = 2;
  }
  // Retry controls whether this build can be retried by CQ.
  Retry retry = 2;

  message Reuse {
    // Regular expression for modes of Runs for which this Reuse block applies.
    // Required.
    //
    // Implicitly wrapped with (?i)^...$  (= complete case-insensitive match).
    //
    // For example,
    //   ".+" will match all modes of Runs,
    //   "dryrun" and "fullrun" will match only Dry and Full runs, respectively.
    string mode_regexp = 1;
    // If deny is true, then reuse of this build in the future Runs of the
    // matched mode is not allowed.
    //
    // If false, then reuse is allowed. It's useful to stop the matching in case
    // of several Reuse messages.
    bool deny = 2;
  }
  // Reuse restricts potential reuse of this build by a later CQ run.
  //
  // DEPRECATED in favor of `reusability`.
  // TODO(crbug/1225047): Remove this after CQDaemon is decommissioned. For now,
  // CQDaemon will still use this field to decide reusability.
  //
  // NOTE: even if reuse is not restricted here, reuse is still subject to other
  // restrictions in applicable project's CQ config.
  //
  // If empty (default), reuse is *allowed*.
  //
  // If specified, the order matters: the first matching Reuse message wins.
  // If specified and no Reuse match the run, reuse is *not allowed*.
  // If any individual Reuse block is invalid, reuse is *not allowed*.
  //
  // Examples:
  //
  //  1. To prohibit reuse only for Full runs, do:
  //     {mode_regexp: "fullrun" deny: true}
  //     {mode_regexp: ".+"      deny: false}
  //
  //  2. To prohibit reuse for everything except Dry Runs, do:
  //     {mode_regexp: "dryrun"}
  repeated Reuse reuse = 3 [deprecated=true];

  message Reusability {
    // mode_allowlist specifies modes of LUCI CV Runs that can reuse this build.
    //
    // If not provided (or empty), all modes are *allowed* for reuse.
    repeated string mode_allowlist = 4;

    // TODO(yiwzhang): Consider adding mode_denylist if necessary.
    // TODO(crbug/753103): add reuse duration or deadline.
  }

  // Reusability restricts potential reuse of this build by a later LUCI CV run.
  //
  // NOTE: even if reuse is not restricted here, reuse is still subject to other
  // restrictions in applicable project's CQ config.
  //
  // If not specified, reuse is *allowed*.
  Reusability reusability = 4;
}