The Gatekeeper, or a project gating system
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

6207 lines
221 KiB

# Copyright 2012 Hewlett-Packard Development Company, L.P.
# Copyright 2021 Acme Gating, LLC
# 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
# 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.
import abc
from collections import OrderedDict, defaultdict, namedtuple, UserDict
import copy
import json
import logging
import os
from functools import total_ordering
import re2
import time
from uuid import uuid4
import urllib.parse
import textwrap
import types
import itertools
from cachetools.func import lru_cache
from zuul.lib import yamlutil as yaml
from zuul.lib.varnames import check_varnames
import jsonpath_rw
from zuul import change_matcher
from zuul.lib.config import get_default
from zuul.lib.result_data import get_artifacts_from_result_data
from zuul.lib.logutil import get_annotated_logger
from zuul.lib.capabilities import capabilities_registry
from zuul.zk.change_cache import ChangeKey
MERGER_MERGE = 1 # "git merge"
MERGER_MERGE_RESOLVE = 2 # "git merge -s resolve"
MERGER_CHERRY_PICK = 3 # "git cherry-pick"
MERGER_SQUASH_MERGE = 4 # "git merge --squash"
'merge': MERGER_MERGE,
'merge-resolve': MERGER_MERGE_RESOLVE,
'cherry-pick': MERGER_CHERRY_PICK,
'squash-merge': MERGER_SQUASH_MERGE,
# Request states
STATE_REQUESTED = 'requested'
STATE_FULFILLED = 'fulfilled'
STATE_FAILED = 'failed'
# Node states
STATE_BUILDING = 'building'
STATE_TESTING = 'testing'
STATE_READY = 'ready'
STATE_IN_USE = 'in-use'
STATE_USED = 'used'
STATE_HOLD = 'hold'
STATE_DELETING = 'deleting'
# Workspace scheme
SCHEME_GOLANG = 'golang'
SCHEME_FLAT = 'flat'
SCHEME_UNIQUE = 'unique' # Internal use only
class ConfigurationErrorKey(object):
"""A class which attempts to uniquely identify configuration errors
based on their file location. It's not perfect, but it's usually
sufficient to determine whether we should show an error to a user.
def __init__(self, context, mark, error_text):
self.context = context
self.mark = mark
self.error_text = error_text
elements = []
if context:
elements.extend([None, None, None])
if mark:
elements.extend([None, None])
self._hash = hash('|'.join([str(x) for x in elements]))
def __hash__(self):
return self._hash
def __ne__(self, other):
return not self.__eq__(other)
def __eq__(self, other):
if not isinstance(other, ConfigurationErrorKey):
return False
return (self.context == other.context and
self.mark == other.mark and
self.error_text == other.error_text)
class ConfigurationError(object):
"""A configuration error"""
def __init__(self, context, mark, error, short_error=None):
self.error = str(error)
self.short_error = short_error
self.key = ConfigurationErrorKey(context, mark, self.error)
class LoadingErrors(object):
"""A configuration errors accumalator attached to a layout object
def __init__(self):
self.errors = []
self.error_keys = set()
def addError(self, context, mark, error, short_error=None):
e = ConfigurationError(context, mark, error, short_error)
def __getitem__(self, index):
return self.errors[index]
def __len__(self):
return len(self.errors)
class NoMatchingParentError(Exception):
"""A job referenced a parent, but that parent had no variants which
matched the current change."""
class TemplateNotFoundError(Exception):
"""A project referenced a template that does not exist."""
class RequirementsError(Exception):
"""A job's requirements were not met."""
class Attributes(object):
"""A class to hold attributes for string formatting."""
def __init__(self, **kw):
setattr(self, '__dict__', kw)
class Freezable(object):
"""A mix-in class so that an object can be made immutable"""
def __init__(self):
super(Freezable, self).__setattr__('_frozen', False)
def freeze(self):
"""Make this object immutable"""
def _freezelist(l):
for i, v in enumerate(l):
if isinstance(v, Freezable):
if not v._frozen:
elif isinstance(v, dict):
l[i] = _freezedict(v)
elif isinstance(v, list):
l[i] = _freezelist(v)
return tuple(l)
def _freezedict(d):
for k, v in list(d.items()):
if isinstance(v, Freezable):
if not v._frozen:
elif isinstance(v, dict):
d[k] = _freezedict(v)
elif isinstance(v, list):
d[k] = _freezelist(v)
return types.MappingProxyType(d)
# Ignore return value from freezedict because __dict__ can't
# be a mappingproxy.
self._frozen = True
def __setattr__(self, name, value):
if self._frozen:
raise Exception("Unable to modify frozen object %s" %
super(Freezable, self).__setattr__(name, value)
class ConfigObject(Freezable):
def __init__(self):
self.source_context = None
self.start_mark = None
class Pipeline(object):
"""A configuration that ties together triggers, reporters and managers
A description of which events should be processed
Responsible for enqueing and dequeing Changes
Communicates success and failure results somewhere
STATE_NORMAL = 'normal'
STATE_ERROR = 'error'
def __init__(self, name, tenant): = name
# Note that pipelines are not portable across tenants (new
# pipeline objects must be made when a tenant is
# reconfigured). A pipeline requires a tenant in order to
# reach the currently active layout for that tenant.
self.tenant = tenant
self.source_context = None
self.start_mark = None
self.description = None
self.failure_message = None
self.merge_failure_message = None
self.success_message = None
self.footer_message = None
self.enqueue_message = None
self.start_message = None
self.dequeue_message = None
self.post_review = False
self.dequeue_on_new_patchset = True
self.ignore_dependencies = False
self.manager = None
self.queues = []
self.relative_priority_queues = {}
self.precedence = PRECEDENCE_NORMAL
self.supercedes = []
self.triggers = []
self.enqueue_actions = []
self.start_actions = []
self.success_actions = []
self.failure_actions = []
self.merge_failure_actions = []
self.no_jobs_actions = []
self.disabled_actions = []
self.dequeue_actions = []
self.disable_at = None
self._consecutive_failures = 0
self._disabled = False
self.window = None
self.window_floor = None
self.window_increase_type = None
self.window_increase_factor = None
self.window_decrease_type = None
self.window_decrease_factor = None
self.state = self.STATE_NORMAL
def actions(self):
return (
self.enqueue_actions +
self.start_actions +
self.success_actions +
self.failure_actions +
self.merge_failure_actions +
self.no_jobs_actions +
self.disabled_actions +
def __repr__(self):
return '<Pipeline %s>' %
def getSafeAttributes(self):
return Attributes(
def validateReferences(self, layout):
# Verify that references to other objects in the layout are
# valid.
for pipeline in self.supercedes:
if not layout.pipelines.get(pipeline):
raise Exception(
'The pipeline "{this}" supercedes an unknown pipeline '
def setManager(self, manager):
self.manager = manager
def addQueue(self, queue):
def getQueue(self, project, branch):
# Queues might be branch specific so match with branch
for queue in self.queues:
if queue.matches(project, branch):
return queue
return None
def getRelativePriorityQueue(self, project):
for queue in self.relative_priority_queues.values():
if project in queue:
return queue
return [project]
def removeQueue(self, queue):
if queue in self.queues:
def getChangesInQueue(self):
changes = []
for shared_queue in self.queues:
changes.extend([x.change for x in shared_queue.queue])
return changes
def getAllItems(self):
items = []
for shared_queue in self.queues:
return items
def formatStatusJSON(self, websocket_url=None):
j_pipeline = dict(,
j_queues = []
j_pipeline['change_queues'] = j_queues
for queue in self.queues:
j_queue = dict(
j_queue['heads'] = []
j_queue['window'] = queue.window
if queue.project_branches and queue.project_branches[0][1]:
j_queue['branch'] = queue.project_branches[0][1]
j_queue['branch'] = None
j_changes = []
for e in queue.queue:
if not e.item_ahead:
if j_changes:
j_changes = []
if (len(j_changes) > 1 and
(j_changes[-2]['remaining_time'] is not None) and
(j_changes[-1]['remaining_time'] is not None)):
j_changes[-1]['remaining_time'] = max(
if j_changes:
return j_pipeline
class ChangeQueue(object):
"""A ChangeQueue contains Changes to be processed for related projects.
A Pipeline with a DependentPipelineManager has multiple parallel
ChangeQueues shared by different projects. For instance, there may a
ChangeQueue shared by interrelated projects foo and bar, and a second queue
for independent project baz.
A Pipeline with an IndependentPipelineManager puts every Change into its
own ChangeQueue.
The ChangeQueue Window is inspired by TCP windows and controlls how many
Changes in a given ChangeQueue will be considered active and ready to
be processed. If a Change succeeds, the Window is increased by
`window_increase_factor`. If a Change fails, the Window is decreased by
A ChangeQueue may be a dynamically created queue, which may be removed
from a DependentPipelineManager once empty.
def __init__(self, pipeline, window=0, window_floor=1,
window_increase_type='linear', window_increase_factor=1,
window_decrease_type='exponential', window_decrease_factor=2,
name=None, dynamic=False):
self.pipeline = pipeline
if name: = name
else: = ''
self.project_branches = []
self._jobs = set()
self.queue = []
self.window = window
self.window_floor = window_floor
self.window_increase_type = window_increase_type
self.window_increase_factor = window_increase_factor
self.window_decrease_type = window_decrease_type
self.window_decrease_factor = window_decrease_factor
self.dynamic = dynamic
def __repr__(self):
return '<ChangeQueue %s: %s>' % (,
def getJobs(self):
return self._jobs
def addProject(self, project, branch):
Adds a project branch combination to the queue.
The queue will match exactly this combination. If the caller doesn't
care about branches it can supply None (but must supply None as well
when matching)
project_branch = (project, branch)
if project_branch not in self.project_branches:
if not =
def matches(self, project, branch):
return (project, branch) in self.project_branches
def enqueueChange(self, change, event):
item = QueueItem(self, change, event)
item.enqueue_time = time.time()
return item
def enqueueItem(self, item):
item.pipeline = self.pipeline
item.queue = self
if self.queue:
item.item_ahead = self.queue[-1]
def dequeueItem(self, item):
if item in self.queue:
if item.item_ahead:
for item_behind in item.items_behind:
if item.item_ahead:
item_behind.item_ahead = item.item_ahead
item.item_ahead = None
item.items_behind = []
item.dequeue_time = time.time()
def moveItem(self, item, item_ahead):
if item.item_ahead == item_ahead:
return False
# Remove from current location
if item.item_ahead:
for item_behind in item.items_behind:
if item.item_ahead:
item_behind.item_ahead = item.item_ahead
# Add to new location
item.item_ahead = item_ahead
item.items_behind = []
if item.item_ahead:
return True
def isActionable(self, item):
if not self.window:
return True
# Ignore done items waiting for bundle dependencies to finish
num_waiting_items = len([
i for i in self.queue
if i.bundle and i.areAllJobsComplete()
window = self.window + num_waiting_items
return item in self.queue[:window]
def increaseWindowSize(self):
if self.window:
if self.window_increase_type == 'linear':
self.window += self.window_increase_factor
elif self.window_increase_type == 'exponential':
self.window *= self.window_increase_factor
def decreaseWindowSize(self):
if self.window:
if self.window_decrease_type == 'linear':
self.window = max(
self.window - self.window_decrease_factor)
elif self.window_decrease_type == 'exponential':
self.window = max(
int(self.window / self.window_decrease_factor))
class Project(object):
"""A Project represents a git repository such as openstack/nova."""
# NOTE: Projects should only be instantiated via a Source object
# so that they are associated with and cached by their Connection.
# This makes a Project instance a unique identifier for a given
# project from a given source.
def __init__(self, name, source, foreign=False): = name
self.source = source
self.connection_name = source.connection.connection_name
self.canonical_hostname = source.canonical_hostname
self.canonical_name = source.canonical_hostname + '/' + name
self.private_secrets_key = None
self.public_secrets_key = None
self.private_ssh_key = None
self.public_ssh_key = None
# foreign projects are those referenced in dependencies
# of layout projects, this should matter
# when deciding whether to enqueue their changes
# TODOv3 (jeblair): re-add support for foreign projects if needed
self.foreign = foreign
def __str__(self):
def __repr__(self):
return '<Project %s>' % (
def getSafeAttributes(self):
return Attributes(
def toDict(self):
d = {}
d['name'] =
d['connection_name'] = self.connection_name
d['canonical_name'] = self.canonical_name
return d
class Node(ConfigObject):
"""A single node for use by a job.
This may represent a request for a node, or an actual node
provided by Nodepool.
def __init__(self, name, label):
super(Node, self).__init__() = name
self.label = label = None
self.lock = None
self.hold_job = None
self.comment = None
self.user_data = None
# Attributes from Nodepool
self._state = 'unknown'
self.state_time = time.time()
self.host_id = None
self.interface_ip = None
self.public_ipv4 = None
self.private_ipv4 = None
self.public_ipv6 = None
self.private_ipv6 = None
self.connection_port = 22
self.connection_type = None
self._keys = [] = None
self.provider = None
self.region = None
self.username = None
self.hold_expiration = None
self.resources = None
self.allocated_to = None
self.attributes = {}
def state(self):
return self._state
def state(self, value):
if value not in NODE_STATES:
raise TypeError("'%s' is not a valid state" % value)
self._state = value
self.state_time = time.time()
def __repr__(self):
return '<Node %s %s:%s>' % (,, self.label)
def __ne__(self, other):
return not self.__eq__(other)
def __eq__(self, other):
if not isinstance(other, Node):
return False
return ( == and
self.label == other.label and ==
def toDict(self, internal_attributes=False):
d = {}
d["id"] =
d['state'] = self.state
d['hold_job'] = self.hold_job
d['comment'] = self.comment
d['user_data'] = self.user_data
for k in self._keys:
d[k] = getattr(self, k)
if internal_attributes:
# These attributes are only useful for the rpc serialization
d['name'] =[0]
d['aliases'] =[1:]
d['label'] = self.label
return d
def updateFromDict(self, data):
self._state = data['state']
keys = []
for k, v in data.items():
if k in ['state', 'name', 'aliases']:
setattr(self, k, v)
self._keys = keys
def fromDict(cls, data):
aliases = data.get('aliases', [])
node = cls([data["name"]] + aliases, data["label"])
return node
class Group(ConfigObject):
"""A logical group of nodes for use by a job.
A Group is a named set of node names that will be provided to
jobs in the inventory to describe logical units where some subset of tasks
def __init__(self, name, nodes):
super(Group, self).__init__() = name
self.nodes = nodes
def __repr__(self):
return '<Group %s %s>' % (, str(self.nodes))
def __ne__(self, other):
return not self.__eq__(other)
def __eq__(self, other):
if not isinstance(other, Group):
return False
return ( == and
self.nodes == other.nodes)
def toDict(self):
return {
'nodes': self.nodes
def fromDict(cls, data):
return cls(data["name"], data["nodes"])
class NodeSet(ConfigObject):
"""A set of nodes.
In configuration, NodeSets are attributes of Jobs indicating that
a Job requires nodes matching this description.
They may appear as top-level configuration objects and be named,
or they may appears anonymously in in-line job definitions.
def __init__(self, name=None):
super(NodeSet, self).__init__() = name or ''
self.nodes = OrderedDict()
self.groups = OrderedDict()
def __ne__(self, other):
return not self.__eq__(other)
def __eq__(self, other):
if not isinstance(other, NodeSet):
return False
return ( == and
self.nodes == other.nodes)
def toDict(self):
d = {}
d['name'] =
d['nodes'] = []
for node in self.nodes.values():
d['groups'] = []
for group in self.groups.values():
return d
def fromDict(cls, data):
nodeset = cls(data["name"])
for node in data["nodes"]:
for group in data["groups"]:
return nodeset
def copy(self):
n = NodeSet(
for name, node in self.nodes.items():
n.addNode(Node(, node.label))
for name, group in self.groups.items():
n.addGroup(Group(, group.nodes[:]))
return n
def addNode(self, node):
for name in
if name in self.nodes:
raise Exception("Duplicate node in %s" % (self,))
self.nodes[tuple(] = node
def getNodes(self):
return list(self.nodes.values())
def addGroup(self, group):
if in self.groups:
raise Exception("Duplicate group in %s" % (self,))
self.groups[] = group
def getGroups(self):
return list(self.groups.values())
def __repr__(self):
name = + ' '
name = ''
return '<NodeSet %s%s>' % (name, list(self.nodes.values()))
def __len__(self):
return len(self.nodes)
class NodeRequest(object):
"""A request for a set of nodes."""
def __init__(self, requestor, build_set_uuid, tenant_name, pipeline_name,
job_name, labels, provider, relative_priority,
self.requestor = requestor
self.build_set_uuid = build_set_uuid
self.tenant_name = tenant_name
self.pipeline_name = pipeline_name
self.job_name = job_name
self.labels = labels
self.nodes = []
self._state = STATE_REQUESTED
self.requested_time = time.time()
self.state_time = time.time()
self.created_time = None
self.stat = None
self.relative_priority = relative_priority
self.provider = provider = None
self._zk_data = {} # Data that we read back from ZK
self.event_id = event_id
# Zuul internal flags (not stored in ZK so they are not
# overwritten).
self.failed = False
self.canceled = False
def reset(self):
# Reset the node request for re-submission
self._zk_data = {}
# Remove any real node information
self.nodes = [] = None
self.state = STATE_REQUESTED
self.stat = None
self.failed = False
self.canceled = False
def fulfilled(self):
return (self._state == STATE_FULFILLED) and not self.failed
def state(self):
return self._state
def state(self, value):
if value not in REQUEST_STATES:
raise TypeError("'%s' is not a valid state" % value)
self._state = value
self.state_time = time.time()
def __repr__(self):
return '<NodeRequest %s %s>' % (, self.labels)
def toDict(self):
Serialize a NodeRequest so it can be stored in ZooKeeper.
Any additional information must be stored in the requestor_data field,
so Nodepool doesn't strip the information when it fulfills the request.
# Start with any previously read data
d = self._zk_data.copy()
# The requestor_data is opaque to nodepool and won't be touched by
# nodepool when it fulfills the request.
d["requestor_data"] = {
"build_set_uuid": self.build_set_uuid,
"tenant_name": self.tenant_name,
"pipeline_name": self.pipeline_name,
"job_name": self.job_name,
d.setdefault('node_types', self.labels)
d.setdefault('requestor', self.requestor)
d.setdefault('created_time', self.created_time)
d.setdefault('provider', self.provider)
# We might change these
d['state'] = self.state
d['state_time'] = self.state_time
d['relative_priority'] = self.relative_priority
d['event_id'] = self.event_id
d['tenant_name'] = self.tenant_name
return d
def updateFromDict(self, data):
self._zk_data = data
self._state = data['state']
self.state_time = data['state_time']
self.relative_priority = data.get('relative_priority', 0)
self.event_id = data['event_id']
# Make sure we don't update tenant_name to 'None'.
# This can happen if nodepool does not report one back and leads
# to errors at other places where we rely on that info.
if 'tenant_name' in data:
self.tenant_name = data['tenant_name']
self.nodes = data.get('nodes', [])
def fromDict(cls, data):
"""Deserialize a NodeRequest from the data in ZooKeeper.
Any additional information must be stored in the requestor_data field,
so Nodepool doesn't strip the information when it fulfills the request.
# The requestor_data contains zuul-specific information which is opaque
# to nodepool and returned as-is when the NodeRequest is fulfilled.
requestor_data = data["requestor_data"]
if requestor_data is None:
requestor_data = {}
request = cls(
relative_priority=data.get("relative_priority", 0),
return request
class Secret(ConfigObject):
"""A collection of private data.
In configuration, Secrets are collections of private data in
key-value pair format. They are defined as top-level
configuration objects and then referenced by Jobs.
def __init__(self, name, source_context):
super(Secret, self).__init__() = name
self.source_context = source_context
# The secret data may or may not be encrypted. This attribute
# is named 'secret_data' to make it easy to search for and
# spot where it is directly used.
self.secret_data = {}
def __ne__(self, other):
return not self.__eq__(other)
def __eq__(self, other):
if not isinstance(other, Secret):
return False
return ( == and
self.source_context == other.source_context and
self.secret_data == other.secret_data)
def areDataEqual(self, other):
return (self.secret_data == other.secret_data)
def __repr__(self):
return '<Secret %s>' % (,)
def _decrypt(self, private_key, secret_data):
# recursive function to decrypt data
if hasattr(secret_data, 'decrypt'):
return secret_data.decrypt(private_key)
if isinstance(secret_data, (dict, types.MappingProxyType)):
decrypted_secret_data = {}
for k, v in secret_data.items():
decrypted_secret_data[k] = self._decrypt(private_key, v)
return decrypted_secret_data
if isinstance(secret_data, (list, tuple)):
decrypted_secret_data = []
for v in secret_data:
decrypted_secret_data.append(self._decrypt(private_key, v))
return decrypted_secret_data
return secret_data
def decrypt(self, private_key):
"""Return a copy of this secret with any encrypted data decrypted.
Note that the original remains encrypted."""
r = Secret(, self.source_context)
r.secret_data = self._decrypt(private_key, self.secret_data)
return r
def serialize(self):
return yaml.encrypted_dump(self.secret_data, default_flow_style=False)
class SecretUse(ConfigObject):
"""A use of a secret in a Job"""
def __init__(self, name, alias):
super(SecretUse, self).__init__() = name
self.alias = alias
self.pass_to_parent = False
class FrozenSecret(ConfigObject):
"""A frozen secret for use by the executor"""
def __init__(self, connection_name, project_name, name, encrypted_data):
super(FrozenSecret, self).__init__()
self.connection_name = connection_name
self.project_name = project_name = name
self.encrypted_data = encrypted_data
def construct_cached(connection_name, project_name, name, encrypted_data):
A caching constructor that enables re-use already existing
FrozenSecret objects.
return FrozenSecret(connection_name, project_name, name,
def toDict(self):
# Name is omitted since this is used in a dictionary
return dict(
class ProjectContext(ConfigObject):
def __init__(self, project_canonical_name, project_name):
self.project_canonical_name = project_canonical_name
self.project_name = project_name
self.branch = None
self.path = None
def __str__(self):
return self.project_name
def toDict(self):
return dict(
class SourceContext(ConfigObject):
"""A reference to the branch of a project in configuration.
Jobs and playbooks reference this to keep track of where they
def __init__(self, project_canonical_name, project_name,
project_connection_name, branch, path, trusted):
super(SourceContext, self).__init__()
# TODO (felix): Would it be enough to only store the project's
# canonical name?
self.project_canonical_name = project_canonical_name
self.project_name = project_name
self.project_connection_name = project_connection_name
self.branch = branch
self.path = path
self.trusted = trusted
self.implied_branch_matchers = None
self.implied_branches = None
def __str__(self):
return '%s/%s@%s' % (
self.project_name, self.path, self.branch)
def __repr__(self):
return '<SourceContext %s trusted:%s>' % (str(self),
def __deepcopy__(self, memo):
return self.copy()
def copy(self):
return self.__class__(
self.project_canonical_name, self.project_name,
self.project_connection_name, self.branch, self.path, self.trusted)
def isSameProject(self, other):
if not isinstance(other, SourceContext):
return False
return (self.project_canonical_name == other.project_canonical_name and
self.trusted == other.trusted)
def __ne__(self, other):
return not self.__eq__(other)
def __eq__(self, other):
if not isinstance(other, SourceContext):
return False
return (self.project_canonical_name == other.project_canonical_name and
self.branch == other.branch and
self.path == other.path and
self.trusted == other.trusted)
def toDict(self):
return dict(
class PlaybookContext(ConfigObject):
"""A reference to a playbook in the context of a project.
Jobs refer to objects of this class for their main, pre, and post
playbooks so that we can keep track of which repos and security
contexts are needed in order to run them.
We also keep a list of roles so that playbooks only run with the
roles which were defined at the point the playbook was defined.
def __init__(self, source_context, path, roles, secrets):
super(PlaybookContext, self).__init__()
self.source_context = source_context
self.path = path
self.roles = roles
# The original SecretUse objects describing how the secret
# should be used
self.secrets = secrets
# FrozenSecret objects which contain only the info the
# executor needs
self.frozen_secrets = ()
def __repr__(self):
return '<PlaybookContext %s %s>' % (self.source_context,
def __ne__(self, other):
return not self.__eq__(other)
def __eq__(self, other):
if not isinstance(other, PlaybookContext):
return False
return (self.source_context == other.source_context and
self.path == other.path and
self.roles == other.roles and
self.secrets == other.secrets)
def copy(self):
r = PlaybookContext(self.source_context,
return r
def validateReferences(self, layout):
# Verify that references to other objects in the layout are
# valid.
for secret_use in self.secrets:
secret = layout.secrets.get(
if secret is None:
raise Exception(
'The secret "{name}" was not found.'.format(
check_varnames({secret_use.alias: ''})
if not secret.source_context.isSameProject(self.source_context):
raise Exception(
"Unable to use secret {name}. Secrets must be "
"defined in the same project in which they "
"are used".format(
project = layout.tenant.getProject(
# Decrypt a copy of the secret to verify it can be done
def freezeSecrets(self, layout):
secrets = []
for secret_use in self.secrets:
secret = layout.secrets.get(
secret_name = secret_use.alias
encrypted_secret_data = secret.serialize()
# Use *our* project, not the secret's, because we want to decrypt
# with *our* key.
project = layout.tenant.getProject(
project.connection_name,, secret_name,
self.frozen_secrets = tuple(secrets)
def addSecrets(self, frozen_secrets):
current_names = set([ for s in self.frozen_secrets])
new_secrets = [s for s in frozen_secrets
if not in current_names]
self.frozen_secrets = self.frozen_secrets + tuple(new_secrets)
def toDict(self, redact_secrets=True):
# Render to a dict to use in passing json to the executor
secrets = {}
for secret in self.frozen_secrets:
if redact_secrets:
secrets[] = 'REDACTED'
secrets[] = secret.toDict()
return dict(
roles=[r.toDict() for r in self.roles],
def toSchemaDict(self):
# Render to a dict to use in REST api
d = {
'path': self.path,
'roles': list(map(lambda x: x.toDict(), self.roles)),
'secrets': [{'name':, 'alias': secret.alias}
for secret in self.secrets],
if self.source_context:
d['source_context'] = self.source_context.toDict()
d['source_context'] = None
return d
class Role(ConfigObject, metaclass=abc.ABCMeta):
"""A reference to an ansible role."""
def __init__(self, target_name):
super(Role, self).__init__()
self.target_name = target_name
def __repr__(self):
def __ne__(self, other):
return not self.__eq__(other)
def __eq__(self, other):
if not isinstance(other, Role):
return False
return (self.target_name == other.target_name)
def toDict(self):
# Render to a dict to use in passing json to the executor
return dict(target_name=self.target_name)
class ZuulRole(Role):
"""A reference to an ansible role in a Zuul project."""
def __init__(self, target_name, project_canonical_name, implicit=False):
super(ZuulRole, self).__init__(target_name)
self.project_canonical_name = project_canonical_name
self.implicit = implicit
def __repr__(self):
return '<ZuulRole %s %s>' % (self.project_canonical_name,
__hash__ = object.__hash__
def __eq__(self, other):
if not isinstance(other, ZuulRole):
return False
# Implicit is not consulted for equality so that we can handle
# implicit to explicit conversions.
return (super(ZuulRole, self).__eq__(other) and
self.project_canonical_name == other.project_canonical_name)
def toDict(self):
# Render to a dict to use in passing json to the executor
d = super(ZuulRole, self).toDict()
d['type'] = 'zuul'
d['project_canonical_name'] = self.project_canonical_name
d['implicit'] = self.implicit
return d
class Job(ConfigObject):
"""A Job represents the defintion of actions to perform.
A Job is an abstract configuration concept. It describes what,
where, and under what circumstances something should be run
(contrast this with Build which is a concrete single execution of
a Job).
NB: Do not modify attributes of this class, set them directly
(e.g., " = ..." rather than "").
BASE_JOB_MARKER = object()
# Pre-allocated empty nodeset so we don't have to allocate a new one
# with every job variant.
empty_nodeset = NodeSet()
def __init__(self, name):
super(Job, self).__init__()
# These attributes may override even the final form of a job
# in the context of a project-pipeline. They can not affect
# the execution of the job, but only whether the job is run
# and how it is reported.
self.context_attributes = dict(
irrelevant_file_matcher=None, # skip-if
ignore_allowed_projects=None, # internal, but inherited
# in the usual manner
# These attributes affect how the job is actually run and more
# care must be taken when overriding them. If a job is
# declared "final", these may not be overridden in a
# project-pipeline.
self.execution_attributes = dict(
# These are generally internal attributes which are not
# accessible via configuration.
self.other_attributes = dict(
secrets=(), # secrets aren't inheritable
waiting_status=None, # Text description of why its waiting
self.attributes = {}
self.attributes.update(self.other_attributes) = name
def combined_variables(self):
Combines the data that has been returned by parent jobs with the
job variables where job variables have priority over parent data.
return Job._deepUpdate(self.parent_data or {}, self.variables)
def toDict(self, tenant):
Convert a Job object's attributes to a dictionary.
d = {}
d['name'] =
d['branches'] = self._branches
d['override_checkout'] = self.override_checkout
d['files'] = self._files
d['irrelevant_files'] = self._irrelevant_files
d['variant_description'] = self.variant_description
if self.source_context:
d['source_context'] = self.source_context.toDict()
d['source_context'] = None
d['description'] = self.description
d['required_projects'] = []
for project in self.required_projects.values():
d['semaphores'] = [s.toDict() for s in self.semaphores]
d['variables'] = self.variables
d['extra_variables'] = self.extra_variables
d['host_variables'] = self.host_variables
d['group_variables'] = self.group_variables
d['final'] =
d['abstract'] = self.abstract
d['intermediate'] = self.intermediate
d['protected'] = self.protected
d['voting'] =
d['timeout'] = self.timeout
d['tags'] = list(self.tags)
d['provides'] = list(self.provides)
d['requires'] = list(self.requires)
d['dependencies'] = list(map(lambda x: x.toDict(), self.dependencies))
d['attempts'] = self.attempts
d['roles'] = list(map(lambda x: x.toDict(), self.roles))
d['run'] = list(map(lambda x: x.toSchemaDict(),
d['pre_run'] = list(map(lambda x: x.toSchemaDict(), self.pre_run))
d['post_run'] = list(map(lambda x: x.toSchemaDict(), self.post_run))
d['cleanup_run'] = list(map(lambda x: x.toSchemaDict(),
d['post_review'] = self.post_review
d['match_on_config_updates'] = self.match_on_config_updates
if self.isBase():
d['parent'] = None
elif self.parent:
d['parent'] = self.parent
d['parent'] = tenant.default_base_job
if isinstance(self.nodeset, str):
ns = tenant.layout.nodesets.get(self.nodeset)
ns = self.nodeset
if ns:
d['nodeset'] = ns.toDict()
if self.ansible_version:
d['ansible_version'] = self.ansible_version
d['ansible_version'] = None
d['workspace_scheme'] = self.workspace_scheme
return d
def __ne__(self, other):
return not self.__eq__(other)
def __eq__(self, other):
# Compare the name and all inheritable attributes to determine
# whether two jobs with the same name are identically
# configured. Useful upon reconfiguration.
if not isinstance(other, Job):
return False
if !=
return False
for k, v in self.attributes.items():
if getattr(self, k) != getattr(other, k):
return False
return True
__hash__ = object.__hash__
def __str__(self):
def __repr__(self):
ln = 0
if self.start_mark:
ln = self.start_mark.line + 1
return '<Job %s branches: %s source: %s#%s>' % (,
def __getattr__(self, name):
v = self.__dict__.get(name)
if v is None:
return self.attributes[name]
return v
def _get(self, name):
return self.__dict__.get(name)
def getSafeAttributes(self):
return Attributes(
def isBase(self):
return self.parent is self.BASE_JOB_MARKER
def setBase(self, layout):
self.inheritance_path = self.inheritance_path + (repr(self),)
if self._get('run') is not None: = self.freezePlaybooks(, layout)
if self._get('pre_run') is not None:
self.pre_run = self.freezePlaybooks(self.pre_run, layout)
if self._get('post_run') is not None:
self.post_run = self.freezePlaybooks(self.post_run, layout)
if self._get('cleanup_run') is not None:
self.cleanup_run = self.freezePlaybooks(self.cleanup_run, layout)
def getNodeSet(self, layout):
if isinstance(self.nodeset, str):
# This references an existing named nodeset in the layout.
ns = layout.nodesets.get(self.nodeset)
if ns is None:
raise Exception(
'The nodeset "{nodeset}" was not found.'.format(
return ns
return self.nodeset
def validateReferences(self, layout):
# Verify that references to other objects in the layout are
# valid.
if not self.isBase() and self.parent:
ns = self.getNodeSet(layout)
if layout.tenant.max_nodes_per_job != -1 and \
len(ns) > layout.tenant.max_nodes_per_job:
raise Exception(
'The job "{job}" exceeds tenant '
'max-nodes-per-job {maxnodes}.'.format(,
for pb in self.pre_run + + self.post_run + self.cleanup_run:
def addRoles(self, roles):
newroles = []
# Start with a copy of the existing roles, but if any of them
# are implicit roles which are identified as explicit in the
# new roles list, replace them with the explicit version.
changed = False
for existing_role in self.roles:
if existing_role in roles:
new_role = roles[roles.index(existing_role)]
new_role = None
if (new_role and
isinstance(new_role, ZuulRole) and
isinstance(existing_role, ZuulRole) and
existing_role.implicit and not new_role.implicit):
changed = True
# Now add the new roles.
for role in reversed(roles):
if role not in newroles:
newroles.insert(0, role)
changed = True
if changed:
self.roles = tuple(newroles)
def getBranches(self):
# Return the raw branch list that match this job
return self._branches
def setBranchMatcher(self, branches, implied=False):
# Set the branch matcher to match any of the supplied branches
self._branches = branches
matchers = []
if implied:
matcher_class = change_matcher.ImpliedBranchMatcher
matcher_class = change_matcher.BranchMatcher
for branch in branches:
self.branch_matcher = change_matcher.MatchAny(matchers)
def setFileMatcher(self, files):
# Set the file matcher to match any of the change files
self._files = files
matchers = []
for fn in files:
self.file_matcher = change_matcher.MatchAnyFiles(matchers)
def setIrrelevantFileMatcher(self, irrelevant_files):
# Set the irrelevant file matcher to match any of the change files
self._irrelevant_files = irrelevant_files
matchers = []
for fn in irrelevant_files:
self.irrelevant_file_matcher = change_matcher.MatchAllFiles(matchers)
def updateVariables(self, other_vars, other_extra_vars, other_host_vars,
if other_vars is not None:
self.variables = Job._deepUpdate(self.variables, other_vars)
if other_extra_vars is not None:
self.extra_variables = Job._deepUpdate(
self.extra_variables, other_extra_vars)
if other_host_vars is not None:
self.host_variables = Job._deepUpdate(
self.host_variables, other_host_vars)
if other_group_vars is not None:
self.group_variables = Job._deepUpdate(
self.group_variables, other_group_vars)
def updateParentData(self, other_build):
# Update variables, but give the new values priority. If more than one
# parent job returns the same variable, the value from the later job
# in the job graph will take precedence.
other_vars = other_build.result_data
v = self.parent_data or {}
v = Job._deepUpdate(v, other_vars)
# To avoid running afoul of checks that jobs don't set zuul
# variables, remove them from parent data here.
v.pop('zuul', None)
# For safety, also drop nodepool and unsafe_vars
v.pop('nodepool', None)
v.pop('unsafe_vars', None)
self.parent_data = v
secret_other_vars = other_build.secret_result_data
v = self.secret_parent_data or {}
v = Job._deepUpdate(secret_other_vars, v)
if 'zuul' in v:
del v['zuul']
self.secret_parent_data = v
artifact_data = self.artifact_data or []
artifacts = get_artifacts_from_result_data(other_vars)
for a in artifacts:
# Change here may be any ref type (tag, change, etc)
ref = other_build.build_set.item.change
# Change is a Branch
if hasattr(ref, 'branch'):
a.update({'branch': ref.branch})
if hasattr(ref, 'number') and hasattr(ref, 'patchset'):
a.update({'change': str(ref.number),
'patchset': ref.patchset})
# Otherwise we are ref type
a.update({'ref': ref.ref,
'oldrev': ref.oldrev,
'newrev': ref.newrev})
if hasattr(ref, 'tag'):
a.update({'tag': ref.tag})
if a not in artifact_data:
if artifact_data:
def updateArtifactData(self, artifact_data):
self.artifact_data = artifact_data
def updateProjectVariables(self, project_vars):
# Merge project/template variables directly into the job
# variables. Job variables override project variables.
self.variables = Job._deepUpdate(project_vars, self.variables)
def updateProjects(self, other_projects):
required_projects = self.required_projects.copy()
self.required_projects = required_projects
def _deepUpdate(a, b):
# Merge nested dictionaries if possible, otherwise, overwrite
# the value in 'a' with the value in 'b'.
ret = {}
for k, av in a.items():
if k not in b:
ret[k] = av
for k, bv in b.items():
av = a.get(k)
if (isinstance(av, (dict, types.MappingProxyType)) and
isinstance(bv, (dict, types.MappingProxyType))):
ret[k] = Job._deepUpdate(av, bv)
ret[k] = bv
return ret
def copy(self):
job = Job(
for k in self.attributes:
v = self._get(k)
if v is not None:
# If this is a config object, it's frozen, so it's
# safe to shallow copy.
setattr(job, k, v)
return job
def freezePlaybooks(self, pblist, layout):
"""Take a list of playbooks, and return a copy of it updated with this
job's roles.
ret = []
for old_pb in pblist:
pb = old_pb.copy()
pb.roles = self.roles
return tuple(ret)
def applyVariant(self, other, layout):
"""Copy the attributes which have been set on the other job to this
if not isinstance(other, Job):
raise Exception("Job unable to inherit from %s" % (other,))
for k in self.execution_attributes:
if (other._get(k) is not None and
k not in set(['final', 'abstract', 'protected',
raise Exception("Unable to modify final job %s attribute "
"%s=%s with variant %s" % (
repr(self), k, other._get(k),
if self.protected_origin:
# this is a protected job, check origin of job definition
this_origin = self.protected_origin
other_origin = other.source_context.project_canonical_name
if this_origin != other_origin:
raise Exception("Job %s which is defined in %s is "
"protected and cannot be inherited "
"from other projects."
% (repr(self), this_origin))
if k not in set(['pre_run', 'run', 'post_run', 'cleanup_run',
'roles', 'variables', 'extra_variables',
'host_variables', 'group_variables',
'required_projects', 'allowed_projects',
setattr(self, k, other._get(k))
# Don't set final above so that we don't trip an error halfway
# through assignment.
if != self.attributes['final']: =
# Abstract may not be reset by a variant, it may only be
# cleared by inheriting.
if !=
self.abstract = other.abstract
elif other.abstract:
self.abstract = True
# An intermediate job may only be inherited by an abstract
# job. Note intermediate jobs must be also be abstract, that
# has been enforced during config reading. Similar to
# abstract, it is cleared by inheriting.
if self.intermediate and not other.abstract:
raise Exception("Intermediate job %s may only inherit "
"to another abstract job" %
if !=
self.intermediate = other.intermediate
elif other.intermediate:
self.intermediate = True
# Protected may only be set to true
if other.protected is not None:
# don't allow to reset protected flag
if not other.protected and self.protected_origin:
raise Exception("Unable to reset protected attribute of job"
" %s by job %s" % (
repr(self), repr(other)))
if not self.protected_origin:
self.protected_origin = \
# We must update roles before any playbook contexts
if other._get('roles') is not None:
# Freeze the nodeset
self.nodeset = self.getNodeSet(layout)
# Pass secrets to parents
secrets_for_parents = [s for s in other.secrets if s.pass_to_parent]
if secrets_for_parents:
frozen_secrets = []
for secret_use in secrets_for_parents:
secret = layout.secrets.get(
if secret is None:
raise Exception("Secret %s not found" % (,))
secret_name = secret_use.alias
encrypted_secret_data = secret.serialize()
# Use the other project, not the secret's, because we
# want to decrypt with the other project's key key.
connection_name = other.source_context.project_connection_name
project_name = other.source_context.project_name
connection_name, project_name,
secret_name, encrypted_secret_data))
# Add the secrets to any existing playbooks. If any of
# them are in an untrusted project, then we've just given
# a secret to a playbook which can run in dynamic config,
# therefore it's no longer safe to run this job
# pre-review. The only way pass-to-parent can work with
# pre-review pipeline is if all playbooks are in the
# trusted context.
for pb in itertools.chain(
self.pre_run,, self.post_run, self.cleanup_run):
if not pb.source_context.trusted:
self.post_review = True
if other._get('run') is not None:
other_run = self.freezePlaybooks(, layout) = other_run
if other._get('pre_run') is not None:
other_pre_run = self.freezePlaybooks(other.pre_run, layout)
self.pre_run = self.pre_run + other_pre_run
if other._get('post_run') is not None:
other_post_run = self.freezePlaybooks(other.post_run, layout)
self.post_run = other_post_run + self.post_run
if other._get('cleanup_run') is not None:
other_cleanup_run = self.freezePlaybooks(other.cleanup_run, layout)
self.cleanup_run = other_cleanup_run + self.cleanup_run
self.updateVariables(other.variables, other.extra_variables,
other.host_variables, other.group_variables)
if other._get('required_projects') is not None:
if (other._get('allowed_projects') is not None and
self._get('allowed_projects') is not None):
self.allowed_projects = frozenset(
elif other._get('allowed_projects') is not None:
self.allowed_projects = other.allowed_projects
if other._get('semaphores') is not None:
# Sort the list of semaphores to avoid issues with
# contention (where two jobs try to start at the same time
# and fail due to acquiring the same semaphores but in
# reverse order.
self.semaphores = tuple(
sorted(other.semaphores + self.semaphores,
key=lambda x:
for k in self.context_attributes:
if (other._get(k) is not None and
k not in set(['tags', 'requires', 'provides'])):
setattr(self, k, other._get(k))
for k in ('tags', 'requires', 'provides'):
if other._get(k) is not None:
setattr(self, k, getattr(self, k).union(other._get(k)))
self.inheritance_path = self.inheritance_path + (repr(other),)
def changeMatchesBranch(self, change, override_branch=None):
if override_branch is None:
branch_change = change
# If an override branch is supplied, create a very basic
# change (a Ref) and set its branch to the override
# branch.
branch_change = Ref(change.project)
branch_change.ref = override_branch
if self.branch_matcher and not self.branch_matcher.matches(
return False
return True
def changeMatchesFiles(self, change):
if self.file_matcher and not self.file_matcher.matches(change):
return False
# NB: This is a negative match.
if (self.irrelevant_file_matcher and
return False
return True
def _projectsFromPlaybooks(self, playbooks, with_implicit=False):
for playbook in playbooks:
# noop job does not have source_context
if playbook.source_context:
yield playbook.source_context.project_canonical_name
for role in playbook.roles:
if role.implicit and not with_implicit:
yield role.project_canonical_name
def getAffectedProjects(self, tenant):
Gets all projects that are required to run this job. This includes
required_projects, referenced playbooks, roles and dependent changes.
project_canonical_names = set()
itertools.chain(self.pre_run, [[0]], self.post_run,
self.cleanup_run), with_implicit=True))
projects = list()
for project_canonical_name in project_canonical_names:
return projects
class JobProject(ConfigObject):
""" A reference to a project from a job. """
def __init__(self, project_name, override_branch=None,
super(JobProject, self).__init__()
self.project_name = project_name
self.override_branch = override_branch
self.override_checkout = override_checkout
def toDict(self):
d = dict()
d['project_name'] = self.project_name
d['override_branch'] = self.override_branch
d['override_checkout'] = self.override_checkout
return d
class JobSemaphore(ConfigObject):
""" A reference to a semaphore from a job. """
def __init__(self, semaphore_name, resources_first=False):
super().__init__() = semaphore_name
self.resources_first = resources_first
def toDict(self):
d = dict()
d['name'] =
d['resources_first'] = self.resources_first
return d
class JobList(ConfigObject):
""" A list of jobs in a project's pipeline. """
def __init__(self):
super(JobList, self).__init__() = OrderedDict() # -> [job, ...]
def addJob(self, job):
if in[].append(job)
else:[] = [job]
def inheritFrom(self, other):
for jobname, jobs in
joblist =, [])
for job in jobs:
if job not in joblist:
class JobDependency(ConfigObject):
""" A reference to another job in the project-pipeline-config. """
def __init__(self, name, soft=False):
super(JobDependency, self).__init__() = name
self.soft = soft
def toDict(self):
return {'name':,
'soft': self.soft}
class JobGraph(object):
""" A JobGraph represents the dependency graph between Job."""
def __init__(self): = OrderedDict() # job_name -> Job
# dependent_job_name -> dict(parent_job_name -> soft)
self._dependencies = {}
self.project_metadata = {}
def __repr__(self):
return '<JobGraph %s>' % (
def addJob(self, job):
# A graph must be created after the job list is frozen,
# therefore we should only get one job with the same name.
if in
raise Exception("Job %s already added" % (,))[] = job
# Append the dependency information
self._dependencies.setdefault(, {})
for dependency in job.dependencies:
# Make sure a circular dependency is never created
ancestor_jobs = self._getParentJobNamesRecursively(, soft=True)
if any(( == anc_job) for anc_job in ancestor_jobs):
raise Exception("Dependency cycle detected in job %s" %
self._dependencies[][] = \
except Exception:
del self._dependencies[]
def getJobs(self):
return list( # Report in the order of layout cfg
def getDirectDependentJobs(self, parent_job, skip_soft=False):
ret = set()
for dependent_name, parents in self._dependencies.items():
part = parent_job in parents \
and (not skip_soft or not parents[parent_job])
if part:
return ret
def getDependentJobsRecursively(self, parent_job, skip_soft=False):
all_dependent_jobs = set()
jobs_to_iterate = set([parent_job])
while len(jobs_to_iterate) > 0:
current_job = jobs_to_iterate.pop()
current_dependent_jobs = self.getDirectDependentJobs(current_job,
new_dependent_jobs = current_dependent_jobs - all_dependent_jobs
jobs_to_iterate |= new_dependent_jobs
all_dependent_jobs |= new_dependent_jobs
return [[name] for name in all_dependent_jobs]
def getParentJobsRecursively(self, dependent_job, layout=None,
return [[name] for name in
def _getParentJobNamesRecursively(self, dependent_job, soft=False,
layout=None, skip_soft=False):
all_parent_jobs = set()
jobs_to_iterate = set([(dependent_job, False)])
while len(jobs_to_iterate) > 0:
(current_job, current_soft) = jobs_to_iterate.pop()
current_parent_jobs = self._dependencies.get(current_job)
if skip_soft:
hard_parent_jobs = \
{d: s for d, s in current_parent_jobs.items() if not s}
current_parent_jobs = hard_parent_jobs
if current_parent_jobs is None:
if soft or current_soft:
if layout:
# If the caller supplied a layout, verify that
# the job exists to provide a helpful error
# message. Called for exception side effect:
current_parent_jobs = {}
raise Exception("Job %s depends on %s which was not run." %
(dependent_job, current_job))
elif dependent_job != current_job:
new_parent_jobs = set(current_parent_jobs.keys()) - all_parent_jobs
for j in new_parent_jobs:
jobs_to_iterate.add((j, current_parent_jobs[j]))
return all_parent_jobs
def getProjectMetadata(self, name):
if name in self.project_metadata:
return self.project_metadata[name]
return None
class JobRequest:
# States:
UNSUBMITTED = "unsubmitted"
REQUESTED = "requested"
HOLD = "hold" # Used by tests to stall processing
RUNNING = "running"
COMPLETED = "completed"
def __init__(self, uuid, precedence=None, state=None, result_path=None):
self.uuid = uuid
if precedence is None:
self.precedence = 0
self.precedence = precedence
if state is None:
self.state = self.UNSUBMITTED
self.state = state
# Path to the future result if requested
self.result_path = result_path
# ZK related data not serialized
self.path = None
self._zstat = None
self.lock = None
def toDict(self):
return {
"uuid": self.uuid,
"state": self.state,
"precedence": self.precedence,
"result_path": self.result_path,
def updateFromDict(self, data):
self.precedence = data["precedence"]
self.state = data["state"]
self.result_path = data["result_path"]
def fromDict(cls, data):
return cls(
def __lt__(self, other):
# Sort requests by precedence and their creation time in
# ZooKeeper in ascending order to prevent older requests from
# starving.
if self.precedence == other.precedence:
if self._zstat and other._zstat:
return self._zstat.ctime < other._zstat.ctime
# NOTE (felix): As the _zstat should always be set when retrieving
# the request from ZooKeeper, this branch shouldn't matter
# much. It's just there, because the _zstat could - theoretically -
# be None.
return self.uuid < other.uuid
return self.precedence < other.precedence
def __eq__(self, other):
same_prec = self.precedence == other.precedence
if self._zstat and other._zstat:
same_ctime = self._zstat.ctime == other._zstat.ctime
same_ctime = self.uuid == other.uuid
return same_prec and same_ctime
def __repr__(self):
return (f"<JobRequest {self.uuid}, state={self.state}, "
f"path={self.path} zone={}>")
class MergeRequest(JobRequest):
# Types:
MERGE = "merge"
CAT = "cat"
REF_STATE = "refstate"
FILES_CHANGES = "fileschanges"
def __init__(self, uuid, job_type, build_set_uuid, tenant_name,
pipeline_name, event_id, precedence=None, state=None,
super().__init__(uuid, precedence, state, result_path)
self.job_type = job_type
self.build_set_uuid = build_set_uuid
self.tenant_name = tenant_name
self.pipeline_name = pipeline_name
self.event_id = event_id
def toDict(self):
d = super().toDict()
"job_type": self.job_type,
"build_set_uuid": self.build_set_uuid,
"tenant_name": self.tenant_name,
"pipeline_name": self.pipeline_name,
"event_id": self.event_id,
return d
def fromDict(cls, data):
return cls(
def __repr__(self):
return (
f"<MergeRequest {self.uuid}, job_type={self.job_type}, "
f"state={self.state}, path={self.path}>"
class BuildRequest(JobRequest):
"""A request for a build in a specific zone"""
# States:
PAUSED = 'paused'
def __init__(self, uuid, zone, build_set_uuid, job_name, tenant_name,
pipeline_name, event_id, precedence=None, state=None,
super().__init__(uuid, precedence, state, result_path) = zone
self.build_set_uuid = build_set_uuid
self.job_name = job_name
self.tenant_name = tenant_name
self.pipeline_name = pipeline_name
self.event_id = event_id
# The executor sets the worker info when it locks the build
# request so that zuul web can use this information to
# build the url for the live log stream.
self.worker_info = None
def toDict(self):
d = super().toDict()
"build_set_uuid": self.build_set_uuid,
"job_name": self.job_name,
"tenant_name": self.tenant_name,
"pipeline_name": self.pipeline_name,
"event_id": self.event_id,
"worker_info": self.worker_info,
return d
def fromDict(cls, data):
request = cls(
request.worker_info = data["worker_info"]
return request
def __repr__(self):
return (
f"<BuildRequest {self.uuid}, state={self.state}, "
f"path={self.path} zone={}>"
class Build(object):
"""A Build is an instance of a single execution of a Job.
While a Job describes what to run, a Build describes an actual
execution of that Job. Each build is associated with exactly one
Job (related builds are grouped together in a BuildSet).
def __init__(self, job, build_set, uuid, zuul_event_id=None):
self.job = job
self.build_set = build_set
self.uuid = uuid
self.url = None
self.result = None
self.result_data = {}
self.error_detail = None
self.execute_time = time.time()
self.start_time = None
self.end_time = None
self.estimated_time = None
self.canceled = False
self.paused = False
self.retry = False
self.held = False
self.parameters = {}
self.worker = Worker()
self.zuul_event_id = zuul_event_id
self.build_request_ref = None
def __repr__(self):
return ('<Build %s of %s voting:%s on %s>' %
(self.uuid,,, self.worker))
def failed(self):
if self.result and self.result not in ['SUCCESS', 'SKIPPED']:
return True
return False
def pipeline(self):
return self.build_set.item.pipeline
def log_url(self):
log_url = self.result_data.get('zuul', {}).get('log_url')
if log_url and log_url[-1] != '/':
log_url = log_url + '/'
return log_url
def getSafeAttributes(self):
return Attributes(uuid=self.uuid,
class Worker(object):
"""Information about the specific worker executing a Build."""
def __init__(self): = "Unknown"
self.hostname = None
self.log_port = None = None
def updateFromData(self, data):
"""Update worker information if contained in the WORK_DATA response.""" = data.get('worker_name',
self.hostname = data.get('worker_hostname', self.hostname)
self.log_port = data.get('worker_log_port', self.log_port) = data.get('worker_zone',
def __repr__(self):
return '<Worker %s>' %
class RepoFiles(object):
"""RepoFiles holds config-file content for per-project job config.
When Zuul asks a merger to prepare a future multiple-repo state
and collect Zuul configuration files so that we can dynamically
load our configuration, this class provides cached access to that
data for use by the Change which updated the config files and any
changes that follow it in a ChangeQueue.
It is attached to a BuildSet since the content of Zuul
configuration files can change with each new BuildSet.
def __init__(self):
self.connections = {}
def __repr__(self):
return '<RepoFiles %s>' % self.connections
def setFiles(self, items):
self.hostnames = {}
for item in items:
connection = self.connections.setdefault(
item['connection'], {})
project = connection.setdefault(item['project'], {})
branch = project.setdefault(item['branch'], {})
def getFile(self, connection_name, project_name, branch, fn):
host = self.connections.get(connection_name, {})
return host.get(project_name, {}).get(branch, {}).get(fn)
class BuildSet(object):
"""A collection of Builds for one specific potential future repository
When Zuul executes Builds for a change, it creates a Build to
represent each execution of each job and a BuildSet to keep track
of all the Builds running for that Change. When Zuul re-executes
Builds for a Change with a different configuration, all of the
running Builds in the BuildSet for that change are aborted, and a
new BuildSet is created to hold the Builds for the Jobs being
run with the new configuration.
A BuildSet also holds the UUID used to produce the Zuul Ref that
builders check out.
# Merge states:
NEW = 1
states_map = {
1: 'NEW',
def __init__(self, item):
self.item = item
self.builds = {}
self.retry_builds = {}
self.result = None
self.uuid = None
self.commit = None
self.dependent_changes = None
self.merger_items = None
self.unable_to_merge = False
self.config_errors = [] # list of ConfigurationErrors
self.failing_reasons = []
self.debug_messages = []
self.warning_messages = []
self.merge_state = self.NEW
self.nodeset_info = {} # job -> dict of nodeset info
self.node_requests = {} # job -> request id
self.files = RepoFiles()
self.repo_state = {}
self.tries = {}
if item.change.files is not None:
self.files_state = self.COMPLETE
self.files_state = self.NEW
self.repo_state_state = self.NEW
def ref(self):
# NOTE(jamielennox): The concept of buildset ref is to be removed and a
# buildset UUID identifier available instead. Currently the ref is
# checked to see if the BuildSet has been configured.
return 'Z' + self.uuid if self.uuid else None
def __repr__(self):
return '<BuildSet item: %s #builds: %s merge state: %s>' % (
def setConfiguration(self):
# The change isn't enqueued until after it's created
# so we don't know what the other changes ahead will be
# until jobs start.
if not self.uuid:
self.uuid = uuid4().hex
if self.dependent_changes is None:
items = []
if self.item.bundle:
items.extend(i for i in self.item.items_ahead if i not in items)
self.dependent_changes = [i.change.toDict() for i in items]
self.merger_items = [i.makeMergerItem() for i in items]
def getStateName(self, state_num):
return self.states_map.get(
state_num, 'UNKNOWN (%s)' % state_num)
def addBuild(self, build):
self.builds[] = build
if not in self.tries:
self.tries[] = 1
def addRetryBuild(self, build):
self.retry_builds.setdefault(, []).append(build)
def removeBuild(self, build):
if not in self.builds: