blob: b8af9185ed4a67b23f108f6f710e6d7274b6d3e6 [file] [log] [blame]
# Copyright 2019 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.
load('@stdlib//internal/graph.star', 'graph')
load('@stdlib//internal/luci/common.star', 'keys', 'triggerer')
load('@stdlib//internal/luci/lib/validate.star', 'validate')
# TODO(vadimsh): Add a doc for 'schedule' syntax and link to it from
# gitiles_poller(schedule=...) and builder(schedule=...).
def gitiles_poller(
name=None,
bucket=None,
repo=None,
refs=None,
refs_regexps=None,
schedule=None,
triggers=None,
):
"""Defines a gitiles poller which can trigger builders on git commits.
It watches a set of git refs and triggers builders if either:
* A watched ref's tip has changed (e.g. a new commit landed on a ref).
* A ref belonging to the watched set has just been created.
The watched ref set is defined via 'refs' and 'refs_regexps' fields. One is
just a simple enumeration of refs, and another allows to use regular
expressions to define what refs belong to the watched set. Both fields can
be used at the same time. If neither is set, the gitiles_poller defaults to
watching "refs/heads/master".
Args:
name: name of the poller, to refer to it from other rules. Required.
bucket: name of the bucket the poller belongs to. Required.
repo: URL of a git repository to poll, starting with https://. Required.
refs: a list of fully qualified refs to watch, e.g. "refs/heads/master" or
"refs/tags/v1.2.3".
refs_regexps: a list of regular expressions that define the watched set of
refs, e.g. "refs/heads/[^/]+" or "refs/branch-heads/\d+\.\d+". The
regular expression should 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-" contains only one slash. The regexp
should not start with ^ or end with $ as they will be added
automatically.
schedule: string with a schedule that describes when to run one iteration
of the poller. It is rare to use custom schedules for pollers.
By default, the poller will run each 30 sec.
triggers: names of builders to trigger whenever the poller detects a new git
commit on any ref in the watched ref set.
"""
name = validate.string('name', name)
bucket = validate.string('bucket', bucket)
refs = validate.list('refs', refs)
for r in refs:
validate.string('refs', r)
refs_regexps = validate.list('refs_regexps', refs_regexps)
for r in refs_regexps:
validate.string('refs_regexps', r)
if not refs and not refs_regexps:
refs = ['refs/heads/master']
# Node that carries the full definition of the poller.
poller_key = keys.gitiles_poller(bucket, name)
graph.add_node(poller_key, props = {
'name': name,
'bucket': bucket,
'repo': validate.string('repo', repo, regexp=r'https://.+'),
'refs': refs,
'refs_regexps': refs_regexps,
'schedule': validate.string('schedule', schedule, required=False),
})
graph.add_edge(keys.bucket(bucket), poller_key)
# Setup nodes that indicate this poller can be referenced in 'triggered_by'
# relations (either via its bucket-scoped name or via its global name).
triggerer_key = triggerer.add(poller_key)
# Link to builders triggered by this builder.
for t in validate.list('triggers', triggers):
graph.add_edge(
parent = triggerer_key,
child = keys.builder_ref(validate.string('triggers', t)),
title = 'triggers',
)