| // Copyright 2018 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. |
| |
| // Schemas for project configs. |
| |
| syntax = "proto3"; |
| |
| package buildbucket; |
| |
| option go_package = "go.chromium.org/luci/buildbucket/proto;buildbucketpb"; |
| |
| import "google/protobuf/duration.proto"; |
| import "google/protobuf/wrappers.proto"; |
| |
| import "go.chromium.org/luci/buildbucket/proto/common.proto"; |
| import "go.chromium.org/luci/common/proto/options.proto"; |
| import "go.chromium.org/luci/resultdb/proto/v1/invocation.proto"; |
| |
| option (luci.file_metadata) = { |
| doc_url: "https://luci-config.appspot.com/schemas/projects:buildbucket.cfg"; |
| }; |
| |
| // A single access control rule. |
| message Acl { |
| |
| // A buildbucket user role. |
| // Defines what a user can do. |
| // |
| // The order of enum member tags is important. |
| // A role with a higher tag number can perform any action that a role with a |
| // lower tag number can perform. |
| enum Role { |
| // Can do read-only operations, such as search for builds. |
| READER = 0; |
| // Same as READER + can schedule and cancel builds. |
| SCHEDULER = 1; |
| // Can do all write operations. |
| WRITER = 2; |
| } |
| // Role denotes a list of actions that an identity can perform. |
| Role role = 1; |
| // Name of the group defined in the auth service. |
| string group = 2; |
| // An email address or a full identity string "kind:name". See auth service |
| // on kinds of identities. Anonymous users are "anonymous:anonymous". |
| // Either identity or group must be present, not both. |
| string identity = 3; |
| } |
| |
| // A set of Acl messages. Can be referenced in a bucket by name. |
| message AclSet { |
| // A name of the ACL set. Required. Must match regex '^[a-z0-9_]+$'. |
| string name = 1; |
| // List of access control rules. |
| // The order does not matter. |
| repeated Acl acls = 2; |
| } |
| |
| |
| // Defines a swarmbucket builder or a builder mixin. A builder has a name, a |
| // category and specifies what should happen if a build is scheduled to that |
| // builder. |
| // |
| // SECURITY WARNING: if adding more fields to this message, keep in mind that |
| // a user that has permissions to schedule a build to the bucket, can override |
| // this config. |
| // |
| // Next tag: 34. |
| message Builder { |
| reserved 8; // cipd_packages |
| reserved 11; // build_numbers of the old format. |
| reserved 13; // auto_builder_dimension of the old format. |
| reserved 15; // experimental of the old format. |
| reserved 19; // luci_migration_host |
| reserved 27; // description of the old format. |
| |
| // Describes a cache directory persisted on a bot. |
| // Prerequisite reading in BuildInfra.Swarming.CacheEntry message in |
| // build.proto. |
| // |
| // To share a builder cache among multiple builders, it can be overridden: |
| // |
| // builders { |
| // name: "a" |
| // caches { |
| // path: "builder" |
| // name: "my_shared_cache" |
| // } |
| // } |
| // builders { |
| // name: "b" |
| // caches { |
| // path: "builder" |
| // name: "my_shared_cache" |
| // } |
| // } |
| // |
| // Builders "a" and "b" share their builder cache. If an "a" build ran on a |
| // bot and left some files in the builder cache and then a "b" build runs on |
| // the same bot, the same files will be available in the builder cache. |
| message CacheEntry { |
| // Identifier of the cache. Length is limited to 128. |
| // Defaults to path. |
| // See also BuildInfra.Swarming.CacheEntry.name in build.proto. |
| string name = 1; |
| |
| // Relative path where the cache in mapped into. Required. |
| // See also BuildInfra.Swarming.CacheEntry.path in build.proto. |
| string path = 2; |
| |
| // Number of seconds to wait for a bot with a warm cache to pick up the |
| // task, before falling back to a bot with a cold (non-existent) cache. |
| // See also BuildInfra.Swarming.CacheEntry.wait_for_warm_cache in build.proto. |
| // The value must be multiples of 60 seconds. |
| int32 wait_for_warm_cache_secs = 3; |
| |
| // Environment variable with this name will be set to the path to the cache |
| // directory. |
| string env_var = 4; |
| } |
| |
| // DEPRECATED. See Builder.executable and Builder.properties |
| // |
| // To specify a recipe name, pass "$recipe_engine" property which is a JSON |
| // object having "recipe" property. |
| message Recipe { |
| // Deprecated "repository" mode used git to bootstrap recipes directly from |
| // the recipe repo. Use `cipd_package` ++ `cipd_version` below instead, as |
| // they are faster, more reliable, and more flexible (because they could be |
| // used to provide non-git, non-python recipes). |
| reserved 1; // repository |
| |
| // Name of the recipe to run. |
| string name = 2; |
| |
| // The CIPD package to fetch the recipes from. |
| // |
| // Typically the package will look like: |
| // |
| // infra/recipe_bundles/chromium.googlesource.com/chromium/tools/build |
| // |
| // Recipes bundled from internal repositories are typically under |
| // `infra_internal/recipe_bundles/...`. |
| // |
| // But if you're building your own recipe bundles, they could be located |
| // elsewhere. |
| string cipd_package = 6; |
| |
| // The CIPD version to fetch. This can be a lower-cased git ref (like |
| // `refs/heads/main` or `head`), or it can be a cipd tag (like |
| // `git_revision:dead...beef`). |
| // |
| // The default is `head`, which corresponds to the git repo's HEAD ref. This |
| // is typically (but not always) a symbolic ref for `refs/heads/master`. |
| string cipd_version = 5; |
| |
| // Colon-separated build properties to set. |
| // Ignored if Builder.properties is set. |
| // |
| // Use this field for string properties and use properties_j for other |
| // types. |
| repeated string properties = 3; |
| |
| // Same as properties, but the value must valid JSON. For example |
| // properties_j: "a:1" |
| // means property a is a number 1, not string "1". |
| // |
| // If null, it means no property must be defined. In particular, it removes |
| // a default value for the property, if any. |
| // |
| // Fields properties and properties_j can be used together, but cannot both |
| // specify values for same property. |
| repeated string properties_j = 4; |
| } |
| |
| // ResultDB-specific information for a builder. |
| message ResultDB { |
| |
| // Whether to enable ResultDB:Buildbucket integration. |
| bool enable = 1; |
| |
| // Configuration for exporting test results to BigQuery. |
| // This can have multiple values to export results to multiple BigQuery |
| // tables, or to support multiple test result predicates. |
| repeated luci.resultdb.v1.BigQueryExport bq_exports = 2; |
| |
| // Specifies if and how to index this build's test results for historical |
| // queries. |
| luci.resultdb.v1.HistoryOptions history_options = 3; |
| } |
| |
| // Buildbucket backend-specific information for a builder. |
| message Backend { |
| // URI for this backend, e.g. "swarming://chromium-swarm". |
| string target = 1; |
| |
| // A string interpreted as JSON encapsulating configuration for this |
| // backend. |
| // TODO(crbug.com/1042991): Move priority, wait_for_capacity, etc. here. |
| string config_json = 2; |
| } |
| |
| // Name of the builder or builder mixin. |
| // |
| // If a builder name, will be propagated to "builder" build tag and |
| // "buildername" recipe property. |
| string name = 1; |
| |
| // Backend for this builder. |
| // If unset, builds are scheduled using the legacy pipeline. |
| Backend backend = 32; |
| |
| // Alternate backend to use for this builder when the |
| // "luci.buildbucket.backend_alt" experiment is enabled. Works even when |
| // `backend` is empty. Useful for migrations to new backends. |
| Backend backend_alt = 33; |
| |
| // Hostname of the swarming instance, e.g. "chromium-swarm.appspot.com". |
| // Required, but defaults to deprecated Swarming.hostname. |
| string swarming_host = 21; |
| |
| // Names of mixins to apply to this builder definition. |
| // |
| // FLATTENING |
| // |
| // Final builder/mixin values are computed as follows: |
| // - start with an empty builder definition. |
| // - if this is a builder, apply values in a bucket's builder_defaults, |
| // flattened in advance. |
| // - apply each mixin, flattened in advance, in the same order. |
| // - apply values in this builder/mixin. |
| // |
| // EXAMPLE |
| // |
| // A definition |
| // |
| // builder_mixins { |
| // name: "foo" |
| // dimensions: "os:Linux" |
| // dimensions: "cpu:x86" |
| // recipe { |
| // repository: "https://example.com" |
| // name: "x" |
| // } |
| // } |
| // builder_mixins { |
| // name: "bar" |
| // dimensions: "cores:8" |
| // dimensions: "cpu:x86-64" |
| // } |
| // bucket { |
| // name: "luci.x.try" |
| // swarming { |
| // builders { |
| // name: "release" |
| // mixins: "foo" |
| // mixins: "bar" |
| // recipe { |
| // name: "y" |
| // } |
| // } |
| // } |
| // } |
| // |
| // is equivalent to |
| // |
| // bucket { |
| // name: "luci.x.try" |
| // swarming { |
| // builders { |
| // name: "release" |
| // dimensions: "os:Linux" |
| // dimensions: "cpu:x86-64" |
| // dimensions: "cores:8" |
| // recipe { |
| // repository: "https://example.com" |
| // name: "y" |
| // } |
| // } |
| // } |
| // } |
| // |
| // A NOTE ON DIAMOND MERGES |
| // |
| // Given |
| // B mixes in A and overrides some values defined in A |
| // C mixes in A |
| // D mixes in B and C |
| // B's overrides won't affect D because D mixes in C after B. |
| // |
| // builder_mixins { |
| // name: "A" |
| // dimensions: "dim:a" |
| // } |
| // builder_mixins { |
| // name: "B" |
| // mixins: "A" |
| // dimensions: "dim:b" |
| // } |
| // builder_mixins { |
| // name: "C" |
| // mixins: "A" |
| // } |
| // ... |
| // builders { |
| // name: "D" |
| // mixins: "B" |
| // mixins: "C" |
| // } |
| // |
| // D's dim will be "a", not "b" because it is "a" in C which is applied after |
| // B. |
| // |
| // OTHER |
| // |
| // Circular references are prohibited. |
| repeated string mixins = 10; |
| |
| // Builder category. Will be used for visual grouping, for example in Code Review. |
| string category = 6; |
| |
| // DEPRECATED. |
| // Used only to enable "vpython:native-python-wrapper" |
| // Does NOT actually propagate to swarming. |
| repeated string swarming_tags = 2; |
| |
| // A requirement for a bot to execute the build. |
| // |
| // Supports 3 forms: |
| // - "<key>:" - exclude the defaults for the key. |
| // Mutually exclusive with other forms. |
| // - "<key>:<value>" - require a bot with this dimension. |
| // This is a shortcut for "0:<key>:<value>", see below. |
| // - "<expiration_secs>:<key>:<value>" - wait for up to expiration_secs. |
| // for a bot with the dimension. |
| // Supports multiple values for different keys and expiration_secs. |
| // expiration_secs must be a multiple of 60. |
| // |
| // When merging a set of dimensions S1 into S2, all dimensions in S1 with a |
| // key K replace all dimensions in S2 with K. This logic is used when applying |
| // builder mixins and dimensions specified in a build request. |
| // |
| // If this builder is defined in a bucket, dimension "pool" is defaulted |
| // to the name of the bucket. See Bucket message below. |
| repeated string dimensions = 3; |
| |
| // Specifies that a recipe to run. |
| // DEPRECATED: use exe. |
| Recipe recipe = 4; |
| |
| // What to run when a build is ready to start. |
| buildbucket.v2.Executable exe = 23; |
| |
| // A JSON object representing Build.input.properties. |
| // Individual object properties can be overridden with |
| // ScheduleBuildRequest.properties. |
| string properties = 24 [(luci.text_pb_format) = JSON]; |
| |
| // Swarming task priority. |
| // A value between 20 and 255, inclusive. |
| // Lower means more important. |
| // |
| // The default value is configured in |
| // https://chrome-internal.googlesource.com/infradata/config/+/master/configs/cr-buildbucket/swarming_task_template.json |
| // |
| // See also https://chromium.googlesource.com/infra/luci/luci-py.git/+/master/appengine/swarming/doc/User-Guide.md#request |
| uint32 priority = 5; |
| |
| // Maximum build execution time. |
| // |
| // Not to be confused with pending time. |
| // |
| // If the timeout is reached, the task will be signaled according to the |
| // `deadline` section of |
| // https://chromium.googlesource.com/infra/luci/luci-py/+/HEAD/client/LUCI_CONTEXT.md |
| // and status_details.timeout is set. |
| // |
| // The task will have `grace_period` amount of time to handle cleanup |
| // before being forcefully terminated. |
| // |
| // NOTE: This corresponds with Build.execution_timeout and |
| // ScheduleBuildRequest.execution_timeout; The name `execution_timeout_secs` and |
| // uint32 type are relics of the past. |
| uint32 execution_timeout_secs = 7; |
| |
| // Maximum build pending time. |
| // |
| // If the timeout is reached, the build is marked as INFRA_FAILURE status |
| // and both status_details.{timeout, resource_exhaustion} are set. |
| // |
| // NOTE: This corresponds with Build.scheduling_timeout and |
| // ScheduleBuildRequest.scheduling_timeout; The name `expiration_secs` and |
| // uint32 type are relics of the past. |
| uint32 expiration_secs = 20; |
| |
| // Amount of cleanup time after execution_timeout_secs. |
| // |
| // After being signaled according to execution_timeout_secs, the task will |
| // have this many seconds to clean up before being forcefully terminated. |
| // |
| // The signalling process is explained in the `deadline` section of |
| // https://chromium.googlesource.com/infra/luci/luci-py/+/HEAD/client/LUCI_CONTEXT.md. |
| // |
| // Defaults to 30s if unspecified or 0. |
| google.protobuf.Duration grace_period = 31; |
| |
| // If YES, will request that swarming wait until it sees at least one bot |
| // report a superset of the requested dimensions. |
| // |
| // If UNSET/NO (the default), swarming will immediately reject a build which |
| // specifies a dimension set that it's never seen before. |
| // |
| // Usually you want this to be UNSET/NO, unless you know that some external |
| // system is working to add bots to swarming which will match the requested |
| // dimensions within expiration_secs. Otherwise you'll have to wait for all of |
| // `expiration_secs` until swarming tells you "Sorry, nothing has dimension |
| // `os:MadeUpOS`". |
| buildbucket.v2.Trinary wait_for_capacity = 29; |
| |
| // Caches that should be present on the bot. |
| repeated CacheEntry caches = 9; |
| |
| // If YES, generate monotonically increasing contiguous numbers for each |
| // build, unique within the builder. |
| // Note: this limits the build creation rate in this builder to 5 per second. |
| Toggle build_numbers = 16; |
| |
| // Email of a service account to run the build as or literal 'bot' string to |
| // use Swarming bot's account (if available). Passed directly to Swarming. |
| // Subject to Swarming's ACLs. |
| string service_account = 12; |
| |
| // If YES, each builder will get extra dimension "builder:<builder name>" |
| // added. Default is UNSET. |
| // |
| // For example, this config |
| // |
| // builder { |
| // name: "linux-compiler" |
| // dimension: "builder:linux-compiler" |
| // } |
| // |
| // is equivalent to this: |
| // |
| // builders { |
| // name: "linux-compiler" |
| // auto_builder_dimension: YES |
| // } |
| // |
| // We've considered providing interpolation like this |
| // builder_defaults { |
| // dimensions: "builder:${BUILDER}" |
| // } |
| // (see also http://docs.buildbot.net/0.8.9/manual/cfg-properties.html#interpolate) |
| // but are currently against complicating config with this. |
| Toggle auto_builder_dimension = 17; |
| |
| // DEPRECATED |
| // |
| // Set the "luci.non_production" experiment in the 'experiments' field below, |
| // instead. |
| // |
| // If YES, sets the "luci.non_production" experiment to 100% for |
| // builds on this builder. |
| // |
| // See the documentation on `experiments` for more details about the |
| // "luci.non_production" experiment. |
| Toggle experimental = 18; |
| |
| // DEPRECATED |
| // |
| // Set the "luci.buildbucket.canary_software" experiment in the 'experiments' |
| // field below, instead. |
| // |
| // Percentage of builds that should use a canary swarming task template. |
| // A value from 0 to 100. |
| // If omitted, a global server-defined default percentage is used. |
| google.protobuf.UInt32Value task_template_canary_percentage = 22; |
| |
| // A mapping of experiment name to the percentage chance (0-100) that it will |
| // apply to builds generated from this builder. Experiments are simply strings |
| // which various parts of the stack (from LUCI services down to your build |
| // scripts) may react to in order to enable certain functionality. |
| // |
| // You may set any experiments you like, but experiments beginning with |
| // "luci." are reserved. Experiment names must conform to |
| // |
| // [a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)* |
| // |
| // Any experiments which are selected for a build show up in |
| // `Build.input.experiments`. |
| // |
| // Its recommended that you confine your experiments to smaller, more explicit |
| // targets. For example, prefer the experiment named |
| // "my_project.use_mysoftware_v2_crbug_999999" rather than "use_next_gen". |
| // |
| // It is NOT recommended to 'piggy-back' on top of existing experiment names |
| // for a different purpose. However if you want to, you can have your build |
| // treat the presence of ANY experiment as equivalent to "luci.non_production" |
| // being set for your build (i.e. "if any experiment is set, don't affect |
| // production"). This is ulimately up to you, however. |
| // |
| // Well-known experiments |
| // |
| // Buildbucket has a number of 'global' experiments which are in various |
| // states of deployment at any given time. For the current state, see |
| // go/buildbucket-settings.cfg. |
| map<string, int32> experiments = 28; |
| |
| // This field will set the default value of the "critical" field of |
| // all the builds of this builder. Please refer to build.proto for |
| // the meaning of this field. |
| // |
| // This value can be overridden by ScheduleBuildRequest.critical |
| buildbucket.v2.Trinary critical = 25; |
| |
| // Used to enable and configure ResultDB integration. |
| ResultDB resultdb = 26; |
| |
| // Description that helps users understand the purpose of the builder, in |
| // HTML. |
| string description_html = 30; |
| } |
| |
| // Configuration of buildbucket-swarming integration for one bucket. |
| message Swarming { |
| // DEPRECATED. Use builder_defaults.swarming_host instead. |
| // Setting this fields sets builder_defaults.swarming_host. |
| string hostname = 1; |
| // DEPRECATED, IGNORED. |
| // Used to generate a URL for Build, may contain parameters |
| // {swarming_hostname}, {task_id}, {bucket} and {builder}. Defaults to: |
| // https://{swarming_hostname}/user/task/{task_id} |
| string url_format = 2; |
| |
| // Defines default values for builders. |
| Builder builder_defaults = 3; |
| |
| // Configuration for each builder. |
| // Swarming tasks are created only for builds for builders that are not |
| // explicitly specified. |
| repeated Builder builders = 4; |
| |
| // DEPRECATED. Use builder_defaults.task_template_canary_percentage instead. |
| // Setting this field sets builder_defaults.task_template_canary_percentage. |
| google.protobuf.UInt32Value task_template_canary_percentage = 5; |
| } |
| |
| // Defines one bucket in buildbucket.cfg |
| message Bucket { |
| // Name of the bucket. Names are unique within one instance of buildbucket. |
| // If another project already uses this name, a config will be rejected. |
| // Name reservation is first-come first-serve. |
| string name = 1; |
| // List of access control rules for the bucket. |
| // The order does not matter. |
| repeated Acl acls = 2; |
| // A list of ACL set names. Each ACL in each referenced ACL set will be |
| // included in this bucket. |
| // The order does not matter. |
| repeated string acl_sets = 4; |
| // Buildbucket-swarming integration. |
| Swarming swarming = 3; |
| } |
| |
| // Schema of buildbucket.cfg file, a project config. |
| message BuildbucketCfg { |
| // All buckets defined for this project. |
| repeated Bucket buckets = 1; |
| // A list of ACL sets. Names must be unique. |
| repeated AclSet acl_sets = 2; |
| // A list of builder mixin definitions. |
| // A mixin can be referenced in any builder defined within the BuildbucketCfg. |
| // See also Buider.mixins field. |
| repeated Builder builder_mixins = 3; |
| } |
| |
| // Toggle is a boolean with an extra state UNSET. |
| // When protobuf messages are merged, UNSET does not overwrite an existing |
| // value. |
| // TODO(nodir): replace with Trinary in ../common.proto. |
| enum Toggle { |
| UNSET = 0; |
| YES = 1; |
| NO = 2; |
| } |