blob: ba9fec907d90cdccf04c3074258181c997236915 [file] [edit]
// Copyright 2025 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
syntax = "proto3";
package turboci.graph.executor.v1;
import "turboci/graph/orchestrator/v1/stage.proto";
import "turboci/graph/orchestrator/v1/stage_execution_policy.proto";
import "turboci/graph/orchestrator/v1/value_data.proto";
import "turboci/graph/orchestrator/v1/workplan.proto";
option go_package = "go.chromium.org/turboci/proto/go/graph/executor/v1;executorpb";
option java_multiple_files = true;
// Request to validate a stage before it is inserted into the graph.
//
// Next ID: 6
message ValidateStageRequest {
// Stage to validate.
optional orchestrator.v1.Stage stage = 1;
// The partial view of the parent work plan.
//
// Stages and Checks are omitted.
optional orchestrator.v1.WorkPlan workplan = 5;
// A map containing [ValueData] for `stage`.
//
// This is key'd by [ValueRef].digest.
map<string, orchestrator.v1.ValueData> value_data = 4;
}
// Response to a stage validation request.
//
// Next ID: 4
message ValidateStageResponse {
// Validated execution policy for the stage.
//
// It SHOULD be based on `stage.execution_policy.requested`. In particular
// executors are expected to populate various unset fields with
// executor-specific defaults (see e.g. `timeout` field in
// StageAttemptExecutionPolicy).
//
// Required.
optional orchestrator.v1.StageExecutionPolicy stage_execution_policy = 1;
// Service accounts the stage can potentially use to call Turbo CI APIs.
//
// The stage attempt token passed to RunStage will be bound to these accounts
// (i.e. it can only be presented together with credentials of some account
// in this set). These accounts will be subjected to an ACL check that
// verifies they are allowed to be used in the work plan at all.
//
// Each entry is either an email or a special value "EUC", which means
// the stage will use the end user credentials of whoever submitted it to
// call Turbo CI APIs.
//
// If omitted, defaults to ["EUC"].
repeated string stage_service_accounts = 2;
// A disambiguating sub-type for this Stage.
//
// Used to identify a specific, named, variant of this stage when many exist,
// to differentiate metrics between stage sub-types. This value should be
// computed by the executor from `args` with some pure function (for example,
// this could be the `config` field of a hypothetical args message, or
// combination of `os` and `flagset` fields).
//
// This must *not* contain high-cardinality data like:
// * ChangeIds or Git Commits
// * Build numbers
// * etc.
//
// This should ideally have high predictive power for the performance
// characteristics of this particular instantiation of this stage - many
// different stages with the same stage args type_url and sub_type should
// perform similarly.
//
// This is *not* intended to be globally unique, but rather to be used to
// group together stages of similar purpose/intent which use the same stage
// args type_url.
//
// If the executor wants the workflow to control this value, it should
// provide a field via the stage args, which the executor can relay to here,
// but cardinality rules still apply, so this should be done with great
// caution. An example of this usage would be a Stage which takes an
// executable payload as part of its args (e.g. a wasm module or starlark
// script). In this case the workflow dictates the execution contents of what
// this Stage will do, and so it makes sense for the executor to allow the
// workflow to directly characterize the performance of this execution via
// sub_type.
//
// As an example, Buildbucket uses this to contain the
// `<bucketname>/<buildername>` (e.g. `try/linux-rel`). Without specifying
// this sub_type, all metrics for `buildbucket.v2.ScheduleBuild` stages would
// be indistinguishable (so the 30s markdown presubmit builder and the 12h+
// ASAN build+test builder would both just show as
// `buildbucket.v2.ScheduleBuild` stages).
//
// Where possible, it is preferable to have uinque Stage arg types instead of
// one big stage type with lots of configurations. This allows the arg types
// to be tailored more closely to the behavior of the actual stage, which
// makes documentation and debugging easier.
//
// Must adhere to the regex: /^[a-zA-Z0-9\(\)\-_./ ]{0,256}$/
optional string stage_sub_type = 3;
}