blob: 816cf7f5f0f9d26bf2ee86b9f0642ea2c13a2d0d [file] [log] [blame]
// 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.
syntax = "proto3";
package cq.config;
option go_package = "config";
import "google/protobuf/duration.proto";
// This message describes a Commit Queue configuration.
//
// The config file commit-queue.cfg should be stored in the config directory of your
// project, alongside cr-buildbucket.cfg.
message Config {
// Optional. If present, the CQ will refrain from processing any CLs,
// on which CQ was triggered after the specified time.
//
// This is an UTC RFC3339 (stiptime(tm)) string representing the time.
// For example, "2017-12-23T15:47:58Z" and Z is required.
string draining_start_time = 1;
// Optional and deprecated.
// URL of the CQ status app to push updates to.
string cq_status_host = 2;
// Optional options for how CLs should be submitted.
SubmitOptions submit_options = 3;
// At least 1 ConfigGroup is required.
repeated ConfigGroup config_groups = 4;
}
// SubmitOptions control how CQ submits CLs.
message SubmitOptions {
// Optional. Maximum number of successful CQ attempts completed by submitting
// corresponding Gerrit CL(s) before waiting burst_delay.
//
// This feature today applies to all attempts processed by this CQ, across all
// config_groups.
//
// Must be >0 to take effect. Requires burst_delay to be set, too.
int32 max_burst = 1;
// Optional. Delay between bursts of submissions of CQ attempts.
// See max_burst for more info.
//
// Must be >0 to take effect. Requires max_burst to be set, too.
google.protobuf.Duration burst_delay = 2;
}
// A boolean with an undefined value.
enum Trinary {
UNSET = 0;
YES = 1;
NO = 2;
}
// ConfigGroup allows one to share single verifiers config across a set of
// Gerrit repositories, which may be in different Gerrit installations.
message ConfigGroup {
// Enumerates repositories on a Gerrit instance for which CQ should work.
message Gerrit {
// Gerrit URL, e.g., https://chromium-review.googlesource.com.
// No trailing slashes allowed.
string url = 1;
// Gerrit projects of this Gerrit instance to work with.
//
// At least 1 required.
repeated Project projects = 2;
message Project {
// Repository name inside Gerrit host. Required.
//
// No leading or trailing slashes allowed, no '.git' at the end.
// 'a/' prefix is also not allowed (it's used on *.googlesource.com for
// forcing authentication).
//
// Examples on https://chromium-review.googlesource.com:
// catapult
// chromium/src
// chromium/tools/depot_tools
string name = 1;
// Limit CLs in this repo to only these refs. Required.
//
// If not specified, defaults to "refs/heads/master".
//
// NOTE: your Gerrit admin must configure Gerrit ACLs such that CQ has
// read access to these refs, otherwise your users will be waiting for CQ
// to act on their CLs forever.
//
// Regular expression is validated by https://github.com/google/re2 library.
//
// NOTE: Git globs aren't supported. Convert them to a regular expression,
// e.g., Git glob "refs/heads/*" should be "refs/heads/[^/]+".
// However, users typically expect "refs/heads/.+", since expectation is
// that every typical Git branch to be CQ-able, including
// "refs/heads/experimental/foobar".
repeated string ref_regexp = 2;
}
}
// At least 1 Gerrit instance with repositories to work with is required.
repeated Gerrit gerrit = 1;
// EXPERIMENTAL!
CQDependOptions cqdepend_options = 3;
// Defines how to verify a CL before submitting it. Required.
Verifiers verifiers = 2;
}
// EXPERIMENTAL! TODO(tandrii, crbug/912294): add doc.
message CQDependOptions {
Trinary allowed = 1;
}
// Verifiers are various types of checks that a Commit Queue performs on a CL.
// All verifiers must pass in order for a CL to be submitted. Configuration file
// describes types of verifiers that should be applied to each CL and their
// parameters.
message Verifiers {
// Required. GerritCQAbility ensures that a user who triggered
// this CQ attempt actually has rights to do so based on 3 factors:
// * membership of the user in committers & dryrunners group,
// * the state of CL/patchset on which CQ is triggered,
// * relationship of the user to the CL.
GerritCQAbility gerrit_cq_ability = 1;
// This verifier is used to check tree status before committing a CL. If the
// tree is closed, then the verifier will wait until it is reopened.
TreeStatus tree_status = 2;
// This verifier triggers a set of builds through Buildbucket.
//
// CQ automatically retries failed tryjobs and only allows CL to land if each
// builder has succeeded in the latest retry.
// If a given tryjob result is too old (>1 day) it is ignored.
//
// Typically, builds from Buildbucket are executed on LUCI stack, however, CQ
// is agnostic to how and where builds are executed.
Tryjob tryjob = 3;
// CQLinter is for internal CQ use only. DO NOT USE IN YOUR cq.cfg.
CQLinter cqlinter = 4;
// Fake is for internal CQ use only. DO NOT USE IN YOUR cq.cfg.
Fake fake = 5;
message GerritCQAbility {
// Required. List of chrome-infra-auth groups, whose members are authorized
// to trigger full CQ runs.
//
// Typically, such groups are named "project-<name>-committers".
repeated string committer_list = 1;
// Optional, but strongly recommended. List of chrome-infra-auth groups,
// whose members are authorized to trigger CQ dry run on Gerrit CLs they own
// (not to be confused with OWNER files) even if CL hasn't been approved.
//
// Typically, such groups are named "project-<name>-tryjob-access".
repeated string dry_run_access_list = 2;
// Optional. allow_submit_with_open_deps controls how CQ full run behaves
// when current Gerrit CL has open dependencies (not yet submitted CLs on
// which *this* CL depends).
//
// If set to false (default), CQ will abort full run attempt immediately if
// open dependencies are detected.
//
// If set to true, then CQ will not abort full run and upon passing all
// other verifiers, CQ will attempt to submit the CL regardless of open
// dependencies and whether CQ verified those open dependencies.
// In turn, if Gerrit project config allows this, Gerrit will execute submit
// of all dependent CLs first and then this CL.
bool allow_submit_with_open_deps = 3;
}
message TreeStatus {
// Required. URL of the project tree status app.
string url = 1;
}
message Tryjob {
// Builders on which tryjobs should be triggered.
repeated Builder builders = 1;
// Optional, defaulting to no retries whatsoever.
RetryConfig retry_config = 2;
message Builder {
// Next field number: 9
// Required. Name of the builder as <project>/<bucket>/<builder>
//
// Examples:
// "chromium/try/linux-tester"
// "other-project/try/shared-try-builder"
//
// For legacy buckets on buildbot, use * as project placeholder, e.g.,
// "*/master.tryserver.example/linux-tester"
string name = 1;
// Optional. If true, a fresh build will be required for each CQ attempt.
//
// Default is false, meaning CQ may re-use a successful build
// triggered before current CQ attempt started.
//
// This option is typically used for builders which run depot_tools'
// PRESUBMIT scripts, which are supposed to be quick to run and provide
// additional OWNERS, lint, etc checks which are useful to run against
// the latest revision of the CL's target branch.
bool disable_reuse = 2;
// Optional name of a builder (aka parent) which will trigger this builder
// (aka child).
//
// If `triggered_by` is not specified (default), CQ will trigger this
// builder directly.
//
// Else, CQ will wait for `triggered_by` (parent) builder to trigger
// (possibly, indirectly) this (child) builder.
// Conditions:
// * `triggered_by` (parent) builder must set a special property
// `triggered_build_ids` upon successful completion with value set
// to a list of triggered Buildbucket build IDs,
// corresponding to each triggered build. One or more of the IDs must
// correspond to this (child) builder, which will then be waited for
// by CQ.
// * parent->child relationship graph must be a forest (set of a trees).
// However, grandparent->parent->child triggering structure isn't well
// tested. Please, talk to CQ maintainers to discuss your use case if you
// actually need it.
//
// Failure/Retry semantics:
// * If `triggered_by` (parent) builder succeeds, but doesn't set
// the right `triggered_build_ids` s.t. CQ can't find this (child)
// builder among triggered builds, then CQ will wait till
// TRYJOB_PENDING_TIMEOUT is reached, currently hardcoded at 2 hours.
// TODO(tandrii,sergiyb): improve this.
// * If this (child) builder fails and CQ still has retry budget,
// CQ will retry a parent builder.
//
// For example, given config:
// builder { name: "*/m/mac_compiler" }
// builder { name: "*/m/mac_tester_10.12"
// triggered_by: "*/m/mac_compiler" }
// builder { name: "*/m/mac_tester_10.13"
// triggered_by: "*/m/mac_compiler" }
// CQ will trigger and wait for "mac_compiler" to succeed. Then, it'll
// check its `triggered_build_ids` and find which ones correspond to
// "mac_tester_10.12" and "mac_tester_10.13" and wait for each to
// complete. If say "mac_tester_10.12" fails, CQ will retry
// "mac_compiler" and expect it to trigger new builds for
// "mac_tester_10.12" and "mac_tester_10.13".
string triggered_by = 3;
// Optional. When this field is present, it marks given builder as
// experimental. It is only triggered on a given percentage of the CLs and
// the outcome does not affect the decicion whether a CL can land or not.
// This is typically used to test new builders and estimate their capacity
// requirements.
float experiment_percentage = 4;
// Optionally specified alternative builder for CQ to choose instead.
// If provided, CQ will choose only one of the equivalent builders as
// required based purely on given CL and CL's owner and **regardless** of
// the possibly already completed try jobs.
//
// Note: none of the equivalent builders should be part of triggered_by
// chain, although CQ may eventually relax this requirement.
EquivalentBuilder equivalent_to = 5;
// Optional. Require this builder only if location_regexp matches a file in
// this CL.
//
// This means:
// * If specified and no file in a CL matches any of the location_regexp,
// then CQ will not care about this builder.
// * If a file in a CL matches any location_regexp_exclude, then this file
// won't be considered when matching location_regexp.
//
// If location_regexp is not specified (default), builder will be used
// on all CLs.
//
// The location_regexp is matches are done against the following string:
// <gerrit_url>/<gerrit_project_name>/+/<cl_file_path>
// File path must be relative to root of the repo, and it uses Unix /
// directory separators.
//
// The comparison is a full match; the pattern is implicitly anchored with
// "^" and "$", so there is no need add them.
//
// Touching a file means either adding, modifying or removing it.
//
// These options currently can not be combined with the following other options:
// * experiment_percentage
// * triggered_by
// * GerritCQAbility.allow_submit_with_open_deps
// If you need to combine them, please talk to CQ owners.
//
// Examples:
//
// location_regexp:
// "https://chromium-review.googlesource.com/chromium/src/[+]/third_party/WebKit/.+"
// will enable builder for all CLs touching any file in
// third_party/WebKit directory of the chromium/src repo, but not
// directory itself.
//
// location_regexp: "https://example.com/repo/[+]/.+"
// location_regexp_exclude: "https://example.com/repo/[+]/all/one.txt"
// will match a CL which touches at least one file other than
// 'one.txt' inside all/ directory of the Gerrit project "repo".
//
// location_regexp_exclude: "https://example.com/.+/[+]/one.txt"
// will match a CL which touches at least one file other than
// 'one.txt' in any repository OR belongs to any other Gerrit server.
// Note, in this case location_regexp defaults to ".*".
repeated string location_regexp = 6;
repeated string location_regexp_exclude = 7;
// If set, this builder will only be triggered when the CL owner is listed
// here.
repeated string owners_whitelist_group = 8;
}
message EquivalentBuilder {
// Required. Name of this builder.
// Format is the same in the same format as Builder.name.
string name = 1;
// Percentage expressing probability of CQ triggering this builder instead
// of the builder to which this builder is equilvanet to.
//
// A choice itself is made deterministicly based on CL alone, hereby
// all CQ attempts on all patchsets of a given CL will trigger the same
// builder, assuming CQ config doesn't change in the mean time.
//
// Note that if `owner_whitelist_group` is also specified, the choice over
// which of the two builders to trigger will be made only for CLs owned by
// whitelisted group.
//
// If not specified, defaults to 0, meaning this builder is never
// triggered by CQ, but an existing build can be re-used by CQ.
//
// To illustrate, suppose percentage=10. Then,
// Without owner_whitelist_group,
// ~10% of all CQ attempts will trigger this builder.
// With owner_whitelist_group set and, suppose, 1/5 of CQ attempts are
// ran on CLs owned by this group, then only ~(1/10)*(1/5) or
// ~2% of all CQ attempts will trigger this builder.
float percentage = 2;
// If specified, limits the builder to CL owners in this group.
string owner_whitelist_group = 3;
}
// Collection of parameters for deciding whether to retry a single build.
// If parameter is not specified, its value defaults to 0 (per proto3).
// Thus, omitting all parameters means no retries of any kind.
message RetryConfig {
// Retry quota for a single tryjob.
int32 single_quota = 1;
// Retry quota for all tryjobs in a CL.
int32 global_quota = 2;
// The weight assigned to each tryjob failure.
int32 failure_weight = 3;
// The weight assigned to each transient failure.
int32 transient_failure_weight = 4;
// The weight assigned to tryjob timeouts.
int32 timeout_weight = 5;
}
}
// CQLinter is for internal use in CQ.
message CQLinter{}
// Fake is for internal use in CQ.
message Fake {
string name = 1;
string eventual_state = 2;
int32 delay = 3;
}
}