milo/api/config/project.proto - infra/luci/luci-go - Git at Google

 // Copyright (c) 2016 The LUCI Authors. All rights reserved.
 // Use of this source code is governed under the Apache License, Version 2.0
 // that can be found in the LICENSE file.

 syntax = "proto3";

 package milo;

 option go_package = "go.chromium.org/luci/milo/api/config";

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

 option (luci.file_metadata) = {
   doc_url: "https://luci-config.appspot.com/schemas/projects:luci-milo.cfg";
 };

 // Note that while the field names in the proto matches the proto
 // naming conventions, the comments uses the generate Go code variable naming
 // conventions.

 // Project is a project definition for Milo.
 message Project {
   reserved 1, 5, 6;

   // Consoles is a list of consoles to define under /console/
   repeated Console consoles = 2;

   // Headers is a list of defined headers that may be referenced by a console.
   repeated Header headers = 3;

   // LogoUrl is the URL to the logo for this project.
   // This field is optional. The logo URL must have a host of
   // storage.googleapis.com.
   string logo_url = 4;

   // IgnoredBuilderIds is a list of builder IDs to be ignored by pubsub handler.
   // Build update events from the builders in this list will be ignored to
   // improve performance.
   // This means that updates to these builders will not be reflected in
   // consoles, the builders page, or the builder groups page.
   // Builders that post updates frequently (> 1/s) should be added to this list.
   // ID format: <bucket>/<builder>
   //
   // TODO(crbug.com/1099036): deprecate this once a long term solution is
   // implemented.
   repeated string ignored_builder_ids = 7;

   // BugUrlTemplate is the template for making a custom bug link for
   // filing a bug against a build that displays on the build page. This
   // is a separate link from the general Milo feedback link that is
   // displayed in the top right corner. This field is optional.
   //
   // The protocal must be `https` and the domain name must be one of the
   // following:
   // * bugs.chromium.org
   // * b.corp.google.com
   //
   // The template is interpreted as a mustache template and the following
   // variables are available:
   // * {{{ build.builder.project }}}
   // * {{{ build.builder.bucket }}}
   // * {{{ build.builder.builder }}}
   // * {{{ milo_build_url }}}
   // * {{{ milo_builder_url }}}
   //
   // All variables are URL component encoded. Additionally, use `{{{ ... }}}` to
   // disable HTML escaping. If the template is not a valid mustache template, or
   // doesn't satisfy the requirements above, the link is not displayed.
   string bug_url_template = 8;
 }

 // Link is a link to an internet resource, which will be rendered out as
 // an anchor tag <a href="url" alt="alt">text</a>.
 message Link {
   // Text is displayed as the text between the anchor tags.
   string text = 1;

   // Url is the URL to link to.
   string url = 2;

   // Alt is the alt text displayed when hovering over the text.
   string alt = 3;
 }

 // Oncall contains information about who is currently scheduled as the
 // oncall (Sheriff, trooper, etc) for certain rotations.
 message Oncall {
   // Name is the name of the oncall rotation being displayed.
   string name = 1;

   // Url is an URL to a json endpoint with the following format:
   // {
   //   "updated_unix_timestamp": <int>,
   //   "emails": [
   //     "email@somewhere.com",
   //     "email@nowhere.com
   //   ]
   // }
   string url = 2;

   // ShowPrimarySecondaryLabels specifies whether the oncaller names
   // should have "(primary)" and "(secondary)" appended to them if there
   // are more than one.
   bool show_primary_secondary_labels = 3;
 }

 // LinkGroup is a list of links, optionally given a name.
 message LinkGroup {
   // Name is the name of this list of links. This is optional.
   string name = 1;

   // Links is a list of links to display.
   repeated Link links = 2;
 }

 // ConsoleSummaryGroup is a list of consoles to be displayed as console summaries
 // (aka the little bubbles at the top of the console).  This can optionally
 // have a group name if specified in the group_link.
 // (e.g. "Tree closers", "Experimental", etc)
 message ConsoleSummaryGroup {
   // Title is a name or label for this group of consoles.  This is optional.
   Link title = 1;

   // ConsoleIds is a list of console ids to display in this console group.
   // Each console id must be prepended with its related project (e.g.
   // chromium/main) because console ids are project-local.
   // Only consoles from the same project are supported.
   // TODO(hinoka): Allow cross-project consoles.
   repeated string console_ids = 2;
 }

 // Header is a collection of links, rotation information, and console summaries
 // that are displayed at the top of a console, below the tree status information.
 // Links and oncall information is always laid out to the left, while
 // console groups are laid out on the right.  Each oncall and links group
 // take up a row.
 message Header {
   // Oncalls are a reference to oncall rotations, which is a URL to a json
   // endpoint with the following format:
   // {
   //   "updated_unix_timestamp": <int>,
   //   "emails": [
   //     "email@somewhere.com",
   //     "email@nowhere.com
   //   ]
   // }
   repeated Oncall oncalls = 1;

   // Links is a list of named groups of web links.
   repeated LinkGroup links = 2;

   // ConsoleGroups are groups of console summaries, each optionally named.
   repeated ConsoleSummaryGroup console_groups = 3;

   // TreeStatusHost is the hostname of the chromium-status instance where
   // the tree status of this console is hosted.  If provided, this will appear
   // as the bar at the very top of the page.
   string tree_status_host = 4;

   // Id is a reference to the header.
   string id = 5;
 }

 // Console is a waterfall definition consisting of one or more builders.
 message Console {
   reserved 8;
   reserved 4;
   reserved "ref";

   // Id is the reference to the console. The console will be visible at the
   // following URL: /p/<Project>/g/<ID>/console.
   string id = 1;

   // Name is the longform name of the waterfall, and will be used to be
   // displayed in the title.
   string name = 2;

   // RepoUrl is the URL of the git repository to display as the rows of the console.
   string repo_url = 3;

   // Refs are the refs to pull commits from when displaying the console.
   //
   // Users can specify a regular expression to match several refs using
   // "regexp:" prefix, but the regular expression must have:
   //   * a literal prefix with at least two slashes present, e.g.
   //     "refs/release-\d+/foobar" is not allowed, because the literal prefix
   //     "refs/release-" only contains one slash, and
   //   * must not start with ^ or end with $ as they are added automatically.
   //
   // For best results, ensure each ref's has commit's **committer** timestamp
   // monotonically non-decreasing. Gerrit will take care of this if you require
   // each commmit to go through Gerrit by prohibiting "git push" on these refs.
   //
   // Eg. refs/heads/main, regexp:refs/branch-heads/\d+\.\d+
   repeated string refs = 14;

   // ExcludeRef is a ref, commits from which are ignored even when they are
   // reachable from the ref specified above. This must be specified as a single
   // fully-qualified ref, i.e. regexp syntax from above is not supported.
   //
   // Note: force pushes to this ref are not supported. Milo uses caching
   // assuming set of commits reachable from this ref may only grow, never lose
   // some commits.
   //
   // E.g. the config below allows to track commits from all release branches,
   // but ignore the commits from the main branch, from which these release
   // branches are branched off:
   //   ref: "regexp:refs/branch-heads/\d+\.\d+"
   //   exlude_ref: "refs/heads/main"
   string exclude_ref = 13;

   // ManifestName the name of the manifest the waterfall looks at.
   // This should always be "REVISION".
   // In the future, other manifest names can be supported.
   // TODO(hinoka,iannucci): crbug/832893 - Support custom manifest names, such as "UNPATCHED" / "PATCHED".
   string manifest_name = 5;

   // Builders is a list of builder configurations to display as the columns of the console.
   repeated Builder builders = 6;

   // FaviconUrl is the URL to the favicon for this console page.
   // This field is optional. The favicon URL must have a host of
   // storage.googleapis.com.
   string favicon_url = 7;

   // Header is a collection of links, rotation information, and console summaries
   // displayed under the tree status but above the main console content.
   Header header = 9;

   // HeaderId is a reference to a header.  Only one of Header or HeaderId should
   // be specified.
   string header_id = 10;

   // If true, this console will not filter out builds marked as Experimental.
   // This field is optional. By default Consoles only show production builds.
   bool include_experimental_builds = 11;

   // If true, only builders view will be available. Console view (i.e. git log
   // based view) will be disabled and users redirected to builder view.
   // Defaults to false.
   bool builder_view_only = 12;

   // If set, will change the default number of commits to query on a single page.
   // If not set, will default to 50.
   int32 default_commit_limit = 15;

   // If set, will default the console page to expanded view.
   // If not set, will default to collapsed view.
   bool default_expand = 16;

   // ExternalProject indicates that this is not a new console, but an external
   // one that should be included from the specified project.
   // If this is set, ExternalId must also be set, and no other fields must be
   // set except for Id and Name.
   string external_project = 17;

   // ExternalId indicates that this is not a new console, but an external one
   // with the specified ID that should be included from ExternalProject.
   // If this is set, ExternalProject must also be set, and no other fields must
   // be set except for Id and Name.
   string external_id = 18;

   // Realm that the console exists under.
   // See https://chromium.googlesource.com/infra/luci/luci-py/+/HEAD/appengine/auth_service/proto/realms_config.proto
   string realm = 19;
 }

 // Builder is a reference to a Milo builder.
 message Builder {
   // Name is the BuilderID of the builders you wish to display for this column
   // in the console. e.g.
   //   * "buildbucket/luci.chromium.try/linux_chromium_rel_ng"
   string name = 1;

   // Category describes the hierarchy of the builder on the header of the
   // console as a "|" delimited list.  Neighboring builders with common ancestors
   // will be have their headers merged.
   // In expanded view, each leaf category OR builder under a non-leaf category
   // will have it's own column.  The recommendation for maximum densification
   // is not to mix subcategories and builders for children of each category.
   string category = 2;

   // ShortName is shorter name of the builder.
   // The recommendation is to keep this name as short as reasonable,
   // as longer names take up more horizontal space.
   string short_name = 3;
 }
	// Copyright (c) 2016 The LUCI Authors. All rights reserved.
	// Use of this source code is governed under the Apache License, Version 2.0
	// that can be found in the LICENSE file.

	syntax = "proto3";

	package milo;

	option go_package = "go.chromium.org/luci/milo/api/config";

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

	option (luci.file_metadata) = {
	doc_url: "https://luci-config.appspot.com/schemas/projects:luci-milo.cfg";
	};

	// Note that while the field names in the proto matches the proto
	// naming conventions, the comments uses the generate Go code variable naming
	// conventions.

	// Project is a project definition for Milo.
	message Project {
	reserved 1, 5, 6;

	// Consoles is a list of consoles to define under /console/
	repeated Console consoles = 2;

	// Headers is a list of defined headers that may be referenced by a console.
	repeated Header headers = 3;

	// LogoUrl is the URL to the logo for this project.
	// This field is optional. The logo URL must have a host of
	// storage.googleapis.com.
	string logo_url = 4;

	// IgnoredBuilderIds is a list of builder IDs to be ignored by pubsub handler.
	// Build update events from the builders in this list will be ignored to
	// improve performance.
	// This means that updates to these builders will not be reflected in
	// consoles, the builders page, or the builder groups page.
	// Builders that post updates frequently (> 1/s) should be added to this list.
	// ID format: <bucket>/<builder>
	//
	// TODO(crbug.com/1099036): deprecate this once a long term solution is
	// implemented.
	repeated string ignored_builder_ids = 7;

	// BugUrlTemplate is the template for making a custom bug link for
	// filing a bug against a build that displays on the build page. This
	// is a separate link from the general Milo feedback link that is
	// displayed in the top right corner. This field is optional.
	//
	// The protocal must be `https` and the domain name must be one of the
	// following:
	// * bugs.chromium.org
	// * b.corp.google.com
	//
	// The template is interpreted as a mustache template and the following
	// variables are available:
	// * {{{ build.builder.project }}}
	// * {{{ build.builder.bucket }}}
	// * {{{ build.builder.builder }}}
	// * {{{ milo_build_url }}}
	// * {{{ milo_builder_url }}}
	//
	// All variables are URL component encoded. Additionally, use `{{{ ... }}}` to
	// disable HTML escaping. If the template is not a valid mustache template, or
	// doesn't satisfy the requirements above, the link is not displayed.
	string bug_url_template = 8;
	}

	// Link is a link to an internet resource, which will be rendered out as
	// an anchor tag <a href="url" alt="alt">text</a>.
	message Link {
	// Text is displayed as the text between the anchor tags.
	string text = 1;

	// Url is the URL to link to.
	string url = 2;

	// Alt is the alt text displayed when hovering over the text.
	string alt = 3;
	}

	// Oncall contains information about who is currently scheduled as the
	// oncall (Sheriff, trooper, etc) for certain rotations.
	message Oncall {
	// Name is the name of the oncall rotation being displayed.
	string name = 1;

	// Url is an URL to a json endpoint with the following format:
	// {
	// "updated_unix_timestamp": <int>,
	// "emails": [
	// "email@somewhere.com",
	// "email@nowhere.com
	// ]
	// }
	string url = 2;

	// ShowPrimarySecondaryLabels specifies whether the oncaller names
	// should have "(primary)" and "(secondary)" appended to them if there
	// are more than one.
	bool show_primary_secondary_labels = 3;
	}

	// LinkGroup is a list of links, optionally given a name.
	message LinkGroup {
	// Name is the name of this list of links. This is optional.
	string name = 1;

	// Links is a list of links to display.
	repeated Link links = 2;
	}

	// ConsoleSummaryGroup is a list of consoles to be displayed as console summaries
	// (aka the little bubbles at the top of the console). This can optionally
	// have a group name if specified in the group_link.
	// (e.g. "Tree closers", "Experimental", etc)
	message ConsoleSummaryGroup {
	// Title is a name or label for this group of consoles. This is optional.
	Link title = 1;

	// ConsoleIds is a list of console ids to display in this console group.
	// Each console id must be prepended with its related project (e.g.
	// chromium/main) because console ids are project-local.
	// Only consoles from the same project are supported.
	// TODO(hinoka): Allow cross-project consoles.
	repeated string console_ids = 2;
	}

	// Header is a collection of links, rotation information, and console summaries
	// that are displayed at the top of a console, below the tree status information.
	// Links and oncall information is always laid out to the left, while
	// console groups are laid out on the right. Each oncall and links group
	// take up a row.
	message Header {
	// Oncalls are a reference to oncall rotations, which is a URL to a json
	// endpoint with the following format:
	// {
	// "updated_unix_timestamp": <int>,
	// "emails": [
	// "email@somewhere.com",
	// "email@nowhere.com
	// ]
	// }
	repeated Oncall oncalls = 1;

	// Links is a list of named groups of web links.
	repeated LinkGroup links = 2;

	// ConsoleGroups are groups of console summaries, each optionally named.
	repeated ConsoleSummaryGroup console_groups = 3;

	// TreeStatusHost is the hostname of the chromium-status instance where
	// the tree status of this console is hosted. If provided, this will appear
	// as the bar at the very top of the page.
	string tree_status_host = 4;

	// Id is a reference to the header.
	string id = 5;
	}

	// Console is a waterfall definition consisting of one or more builders.
	message Console {
	reserved 8;
	reserved 4;
	reserved "ref";

	// Id is the reference to the console. The console will be visible at the
	// following URL: /p/<Project>/g/<ID>/console.
	string id = 1;

	// Name is the longform name of the waterfall, and will be used to be
	// displayed in the title.
	string name = 2;

	// RepoUrl is the URL of the git repository to display as the rows of the console.
	string repo_url = 3;

	// Refs are the refs to pull commits from when displaying the console.
	//
	// Users can specify a regular expression to match several refs using
	// "regexp:" prefix, but the regular expression must have:
	// * a literal prefix with at least two slashes present, e.g.
	// "refs/release-\d+/foobar" is not allowed, because the literal prefix
	// "refs/release-" only contains one slash, and
	// * must not start with ^ or end with $ as they are added automatically.
	//
	// For best results, ensure each ref's has commit's committer timestamp
	// monotonically non-decreasing. Gerrit will take care of this if you require
	// each commmit to go through Gerrit by prohibiting "git push" on these refs.
	//
	// Eg. refs/heads/main, regexp:refs/branch-heads/\d+\.\d+
	repeated string refs = 14;

	// ExcludeRef is a ref, commits from which are ignored even when they are
	// reachable from the ref specified above. This must be specified as a single
	// fully-qualified ref, i.e. regexp syntax from above is not supported.
	//
	// Note: force pushes to this ref are not supported. Milo uses caching
	// assuming set of commits reachable from this ref may only grow, never lose
	// some commits.
	//
	// E.g. the config below allows to track commits from all release branches,
	// but ignore the commits from the main branch, from which these release
	// branches are branched off:
	// ref: "regexp:refs/branch-heads/\d+\.\d+"
	// exlude_ref: "refs/heads/main"
	string exclude_ref = 13;

	// ManifestName the name of the manifest the waterfall looks at.
	// This should always be "REVISION".
	// In the future, other manifest names can be supported.
	// TODO(hinoka,iannucci): crbug/832893 - Support custom manifest names, such as "UNPATCHED" / "PATCHED".
	string manifest_name = 5;

	// Builders is a list of builder configurations to display as the columns of the console.
	repeated Builder builders = 6;

	// FaviconUrl is the URL to the favicon for this console page.
	// This field is optional. The favicon URL must have a host of
	// storage.googleapis.com.
	string favicon_url = 7;

	// Header is a collection of links, rotation information, and console summaries
	// displayed under the tree status but above the main console content.
	Header header = 9;

	// HeaderId is a reference to a header. Only one of Header or HeaderId should
	// be specified.
	string header_id = 10;

	// If true, this console will not filter out builds marked as Experimental.
	// This field is optional. By default Consoles only show production builds.
	bool include_experimental_builds = 11;

	// If true, only builders view will be available. Console view (i.e. git log
	// based view) will be disabled and users redirected to builder view.
	// Defaults to false.
	bool builder_view_only = 12;

	// If set, will change the default number of commits to query on a single page.
	// If not set, will default to 50.
	int32 default_commit_limit = 15;

	// If set, will default the console page to expanded view.
	// If not set, will default to collapsed view.
	bool default_expand = 16;

	// ExternalProject indicates that this is not a new console, but an external
	// one that should be included from the specified project.
	// If this is set, ExternalId must also be set, and no other fields must be
	// set except for Id and Name.
	string external_project = 17;

	// ExternalId indicates that this is not a new console, but an external one
	// with the specified ID that should be included from ExternalProject.
	// If this is set, ExternalProject must also be set, and no other fields must
	// be set except for Id and Name.
	string external_id = 18;

	// Realm that the console exists under.
	// See https://chromium.googlesource.com/infra/luci/luci-py/+/HEAD/appengine/auth_service/proto/realms_config.proto
	string realm = 19;
	}

	// Builder is a reference to a Milo builder.
	message Builder {
	// Name is the BuilderID of the builders you wish to display for this column
	// in the console. e.g.
	// * "buildbucket/luci.chromium.try/linux_chromium_rel_ng"
	string name = 1;

	// Category describes the hierarchy of the builder on the header of the
	// console as a "\|" delimited list. Neighboring builders with common ancestors
	// will be have their headers merged.
	// In expanded view, each leaf category OR builder under a non-leaf category
	// will have it's own column. The recommendation for maximum densification
	// is not to mix subcategories and builders for children of each category.
	string category = 2;

	// ShortName is shorter name of the builder.
	// The recommendation is to keep this name as short as reasonable,
	// as longer names take up more horizontal space.
	string short_name = 3;
	}