recipe_proto/infra/fuchsia.proto

// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto3";

import "go.chromium.org/luci/common/proto/options.proto";

package infra.fuchsia;  // `from PB.infra.fuchsia import Fuchsia`

option go_package = "recipes";

option(luci.file_metadata) = {
  doc_url :
      "https://fuchsia.googlesource.com/infra/recipes/+/HEAD/recipe_proto/"
      "infra/fuchsia.proto";
}
;

// Fuchsia fully describes how to execute a Fuchsia CI/CQ task. It defines the
// schema used by the properties that are consumed by the fuchsia recipes.
//
// WARNING: This message's schema is used for deserializing jsonpb properties.
// Many of the backwards-compatibility guarantees provided by protobufs only
// apply when using binary encoding, not when using JSON.  For example, renaming
// a field or marking a field as "reserved" in this message will break
// deserialization of any JSON protos that have that field set. Be very careful
// when making changes to fields in this message.
message Fuchsia {
  // (required) How to obtain the Fuchsia build inputs. See Checkout docs.
  Checkout checkout = 1;

  // (required) How to build Fuchsia. See Build docs.
  Build build = 2;

  // How to test Fuchsia. See Test docs.
  Test test = 3;

  // The GCS bucket to upload results to.
  // TODO(fxbug.dev/37264): consider eventually deprecating in favour of
  // artifact_gcs_bucket.
  string gcs_bucket = 4;

  // The GCS bucket to upload build artifacts to.
  string artifact_gcs_bucket = 5;

  // How to test Fuchsia in external infrastructures. See ExternalTests docs.
  ExternalTests external_tests = 6;

  // Describes how to fetch the Fuchsia build inputs.
  message Checkout {
    // Jiri <package> atttribute values indicating additional packages to fetch
    // from the input manifest. By default, packages with attribute tags are
    // skipped unless one or more of the attribute values are specified here.
    repeated string attributes = 1;

    // The name of the manifest to import from the integration repository.
    string manifest = 2;

    // Jiri remote manifest project,
    //
    // TODO(fxbug.dev/9896): This should always be "integration" and is
    // redundant because we can select the proper integration repo using the
    // build input. Delete this in favor of a hard-coded constant since this
    // value will only ever change if we completely restructure our CI/CD model
    // or rename the integration repo, and thus this recipe.
    string project = 3;

    // The remote integration manifest repository.
    string remote = 4;

    // Whether or not checkout is a release version.
    bool is_release_version = 5;

    // Whether or not to upload checkout results to cloud storage.
    // If true, gcs_bucket must be set.
    // TODO(fxbug.dev/65086): Delete once protos no longer reference it.
    bool upload_results = 6;

    // The minimum distance between HEAD and a cached checkout revision
    // at which we enforce a rebase to HEAD.
    int32 min_rebase_distance = 7;
  }

  // Describes how to build Fuchsia.
  message Build {
    // The path within the checkout to a textproto file containing build
    // parameters to pass to fint.
    string fint_params_path = 1;

    // Tags of environments on which the testsharder will key
    repeated string environment_tags = 2;

    // Whether to run any tests.
    bool run_tests = 3;

    // Whether build is an SDK subbuild.
    bool sdk_subbuild = 4;

    // Whether or not to upload build results to cloud storage.
    // If true, gcs_bucket must be set.
    bool upload_results = 5;

    // Whether to sign the artifacts.
    bool sign_artifacts = 6;

    // The GCS bucket to upload build stats to.
    string stats_gcs_bucket = 7;

    // How long to wait until timing out `fint build`.
    int32 timeout_secs = 8;

    // Whether to perform an incremental build.
    // TODO(olivernewman): This field no longer affects the behavior of the
    // `build` recipe module, only the `checkout` recipe module. Replace it with
    // an appropriately named `Checkout` field.
    bool incremental = 9;

    // Whether to generate codesize report.
    bool run_codesize = 10;

    // CI bucket of the builder to use for size diffing. This field controls
    // whether a size diff will be computed.
    string size_diff_ci_bucket = 11;

    // CI builder name of the builder to use for size diffing. This can be set
    // to override the default of using the current builder's name.
    string size_diff_ci_builder = 12;

    // The review label to use for size creep exemption. This field controls
    // whether size creep budgets are enforced.
    string size_creep_label = 13;

    // The CIPD package to which assembly inputs should be uploaded. No upload
    // will happen if this is empty.
    string assembly_artifacts_cipd_package = 14;
  }

  // Describes how to test Fuchsia.
  message Test {
    // Whether to pave images the device for testing. (Ignored if
    // device_type == QEMU)
    bool pave = 1;

    // Swarming pool from which a test task will be drawn
    string pool = 2;

    // How long to wait for Swarming to find a bot on which to test
    int32 swarming_expiration_timeout_secs = 3;

    // How long to wait (in seconds) before killing the test
    // swarming task if there's no output being produced
    int32 swarming_io_timeout_secs = 4;

    // How long to wait until timing out on tests.
    int32 timeout_secs = 5;

    // Target number of tests in a given testing swarming task ("max" name is a
    // historical artifact).
    // Deprecated in favor of target_shard_duration_secs
    int32 max_shard_size = 6;

    // Maximum number of attempts to make for each individual shard.
    // 1 means that shards will not be retried if they fail.
    //
    // If this protobuf field is 0 (the default for this field), the recipe
    // will use a non-zero default for the maximum number of attempts.
    int32 max_attempts = 7;

    // Whether to use runtests by default when running fuchsia tests; if false,
    // run_test_component will be used.
    bool use_runtests = 8;

    // A default service account to attach to test tasks; used for shards that
    // do not specify one themselves.
    string default_service_account = 9;

    // Any test that executes for longer than this will be considered failed.
    // 0 means no timeout.
    uint32 per_test_timeout_secs = 10;

    // Whether or not to upload build results to cloud storage.
    // If true, gcs_bucket must be set.
    bool upload_results = 11;

    // Whether or not to pave using images from GCS.
    bool pave_from_gcs = 12;

    // Whether the test task needs to require a device with serial, QEMU
    // conventionally always having 'serial' enabled.
    bool targets_serial = 13;

    // If >0, will keep launching tasks until this many seconds have
    // elapsed. max_attempts should be set to 1 if this is >0.
    uint32 rerun_budget_secs = 14;

    // If >0, will distribute tests into shards that are each expected to take
    // approximately this duration.
    uint32 target_shard_duration_secs = 15;

    // Maximum number of shards allowed per test environment. If 0, will not
    // pass a max to testsharder (so testsharder will use the hardcoded default
    // max). If <0, testsharder will not set a max at all.
    int32 max_shards_per_env = 16;

    // These two fields specify the names the builder should use when
    // uploading performance test results to the Catapult performance
    // dashboard. If these are absent, the builder should not upload
    // results to Catapult.
    //
    // These correspond to the "masters" and "bots" fields described here:
    // https://fuchsia.googlesource.com/fuchsia/+/main/garnet/bin/catapult_converter/README.md
    // https://chromium.googlesource.com/catapult/+/main/docs/how-to-write-metrics.md
    string catapult_dashboard_master = 17;
    string catapult_dashboard_bot = 18;

    // Kernel command-line arguments to pass on boot.
    repeated string zircon_args = 19;

    // Maximum number of attempts for running each individual test within a
    // Swarming task (shard). A value of 0 is treated as 1.
    //
    // Setting this to 0 or 1 disables retries within tasks, but retries of
    // whole tasks may still be enabled via retry_task_on_test_failure.
    int32 max_attempts_per_test = 20;

    // Whether to enable task-level retries for test failures.
    bool retry_task_on_test_failure = 21;

    // If >0, and the number of affected tests is <= this threshold, then
    // the recipe will tell testsharder to multiply the affected tests.
    uint32 affected_tests_multiply_threshold = 22;

    // Describes how to interact with the GCE Mediator to test Fuchsia on GCE.
    message GCEMediator {
      // URL of the GCE Mediator endpoint.
      string endpoint = 1;
      // Cloud project to create Fuchsia VMs in.
      string cloud_project = 2;
      // TODO(https://fxbug.dev/82640): Move this to test specs.
      string machine_shape = 3;
    }
    GCEMediator gce_mediator = 23;

    // Whether to enable using ffx in infra.
    bool use_ffx = 24;

    // Whether to enable using experimental ffx features in infra.
    bool use_ffx_experimental = 25;

    // Whether to use CAS to transfer test artifacts.
    bool use_cas = 26;

    // A list of device types to NOT run tests on.
    // This should only be used to avoid running on physical devices where
    // there are capacity concerns.
    repeated string disabled_device_types = 27;
  }

  // Describes how to test Fuchsia in external infrastructures.
  message ExternalTests {
    // Name of system image under test.
    string system_image = 1;

    // TAP projects to trigger.
    repeated string tap_projects = 2;

    // Whether to use staging host for RPCs.
    bool use_staging_host = 3;

    // How long to wait for external tests to finish.
    int32 timeout_secs = 4;
  }
}