Data Model

It all starts with the Pipeline. A Pipeline is the basic organizational structure that everything else hangs off.

class zuul.model.Pipeline(name, tenant)

A configuration that ties together triggers, reporters and managers

Trigger: A description of which events should be processed
Manager: Responsible for enqueing and dequeing Changes
Reporter: Communicates success and failure results somewhere

Pipelines have a configured PipelineManager which controlls how the Ref objects are enqueued and processed.

There are currently two, DependentPipelineManager and IndependentPipelineManager

class zuul.manager.PipelineManager(sched, pipeline): Abstract Base Class for enqueing and processing Changes in a Pipeline

class zuul.manager.dependent.DependentPipelineManager(*args, **kwargs)

PipelineManager for handling interrelated Changes.

The DependentPipelineManager puts Changes that share a Pipeline into a shared ChangeQueue. It then processes them using the Optimistic Branch Prediction logic with Nearest Non-Failing Item reparenting algorithm for handling errors.

class zuul.manager.independent.IndependentPipelineManager(sched, pipeline): PipelineManager that puts every Change into its own ChangeQueue.

A Pipeline has one or more ChangeQueue objects.

class zuul.model.ChangeQueue

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 window_decrease_factor.

A ChangeQueue may be a dynamically created queue, which may be removed from a DependentPipelineManager once empty.

A Job represents the definition of what to do. A Build represents a single run of a Job. A JobGraph is used to encapsulate the dependencies between one or more Job objects.

class zuul.model.Job(name)

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., “job.run = …” rather than “job.run.append(…)”).

class zuul.model.JobGraph(job_map)

A JobGraph represents the dependency graph between Jobs.

This class is an attribute of the BuildSet, and should not be modified after its initial creation.

class zuul.model.Build

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).

The PipelineManager enqueues each Ref into the ChangeQueue in a QueueItem.

class zuul.model.QueueItem

Represents the position of a Change in a ChangeQueue.

All Changes are enqueued into ChangeQueue in a QueueItem. The QueueItem holds the current BuildSet as well as all previous BuildSets that were produced for this QueueItem.

As the Changes are processed, each Build is put into a BuildSet

class zuul.model.BuildSet

A collection of Builds for one specific potential future repository state.

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.

Changes

class zuul.model.Change(project): A proposed new state for a Project.

class zuul.model.Ref(project): An existing state of a Project.

Filters

class zuul.model.RefFilter(connection_name): Allows a Manager to only enqueue Changes that meet certain criteria.

class zuul.model.EventFilter(connection_name, trigger): Allows a Pipeline to only respond to certain events.

Tenants

An abide is a collection of tenants.

class zuul.model.Tenant(name)

class zuul.model.UnparsedAbideConfig

A collection of yaml lists that has not yet been parsed into objects.

An Abide is a collection of tenants and access rules to those tenants.

class zuul.model.UnparsedConfig: A collection of yaml lists that has not yet been parsed into objects.

class zuul.model.ParsedConfig: A collection of parsed config objects.

Other Global Objects

class zuul.model.Project(name, source, foreign=False): A Project represents a git repository such as openstack/nova.

class zuul.model.Layout(tenant, uuid=None): Holds all of the Pipelines.

class zuul.model.RepoFiles

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.

class zuul.model.TriggerEvent: Incoming event from an external system.