buildbucket/client/cmd/buildbucket/proto/project_config.proto

// Copyright 2015 The Swarming Authors. All rights reserved.
// Use of this source code is governed by the Apache v2.0 license that can be
// found in the LICENSE file.

// Schemas for project configs.

syntax = "proto2";

package buildbucket;

// A single access control rule.
message Acl {
  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.
  optional Role role = 1;
  // Name of the group defined in the auth service.
  optional 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.
  optional 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_]+$'.
  optional string name = 1;
  // List of access control rules.
  // The order does not matter.
  repeated Acl acls = 2;
}

// Configuration of buildbucket-swarming integration for one bucket.
message Swarming {
  message Recipe {
    // Repository URL of the recipe package.
    optional string repository = 1;
    // Name of the recipe to run.
    optional string name = 2;
    // colon-separated build properties to set.
    // A property can be overriden by "properties" build parameter.
    //
    // 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;
  }

  // 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.
  message Builder {
    message CipdPackage {
      // A template of a full CIPD package name, e.g
      // "infra/tools/authutil/${platform}". This can be parametrized using
      // ${platform} and ${os_ver} parameters, where ${platform} will be
      // expanded into "<os>-<architecture>" and ${os_ver} will be expanded to
      // OS version name.
      optional string package_name = 1;
      // Path to dir, relative to the task working dir, where to install the
      // package. The path cannot be empty or start with a slash.
      optional string path = 2;
      // Valid package version for all packages matched by package name.
      optional string version = 3;
    }

    // Describes a named cache that should be present on the bot.
    // See also https://github.com/luci/luci-py/blob/3a2941345cf011a96bcd83d76328395323245bb5/appengine/swarming/swarming_rpcs.py#L166
    message CacheEntry {
      // Unique name of the cache. Required. Length is limited to 4096.
      optional string name = 1;
      // Relative path to the directory that will be linked to the named cache.
      // Required.
      // A path cannot be shared among multiple caches or CIPD installations.
      // A task will fail if a file/dir with the same name already exists.
      optional string path = 2;
    }

    // Name of the builder. Will be propagated to "builder" build tag and
    // "buildername" recipe property.
    optional string name = 1;
    // Builder category. Will be used for visual grouping, for example in Code Review.
    optional string category = 6;
    // Will be become to swarming task tags.
    // Each tag will end up in "swarming_tag" buildbucket tag, for example
    // "swarming_tag:builder:release"
    repeated string swarming_tags = 2;
    // Colon-delimited key-value pair of task dimensions.
    //
    // If value is not specified ("<key>:"), then it excludes a default value.
    repeated string dimensions = 3;
    // CIPD packages to install on the builder.
    repeated CipdPackage cipd_packages = 8;
    // Specifies that a recipe to run.
    optional Recipe recipe = 4;
    // Swarming task priority.
    optional uint32 priority = 5;
    // Maximum build execution time. Not to be confused with pending time.
    optional uint32 execution_timeout_secs = 7;
    // Caches that should be present on the bot.
    repeated CacheEntry caches = 9;
  }

  // Hostname of the swarming instance, e.g. "chromium-swarm.appspot.com".
  optional string hostname = 1;
  // 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}
  optional string url_format = 2;

  // Defines default values for builders.
  optional 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;

  // Percentage of builds that should use a canary swarming task template.
  // A value from 0 to 100.
  optional uint32 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.
  optional 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.
  optional 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;
}