| // 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; | |
| } |