CDEvents Documentation

• 1:
• 2:
• 3:
• 4:
• 5:
• 6:
• 7:
• 8:
• 9:
• 10:

CDEvents specification

1 -

CDEvents Primer

Abstract

This non-normative document provides an overview of the CDEvents specification. It is meant to complement the CDEvents specification to provide additional background and insight into the history and design decisions made during the development of the specification. This allows the specification itself to focus on the normative technical details.

When new features are added to the CDEvents specification, the CDEvents primer document is updated accordingly to reflect the design decisions behind the change.

Table of Contents

• History
• Design reflections
  • How does CDEvents enable tools to communicate in an interoperable way?
  • Why use events?
  • Why not point-to-point communication?
  • Declarative vs. imperative events
• Relations to CloudEvents
• Versioning
  • Versioning of CDEvents
  • Versioning of the CDEvents specification
  • Development of a new version
• Extending CDEvents
  • Adding new data to CDEvents
  • Adding new event types
• Adopting CDEvents
  • Producer-side architectures
    • External event producer
    • External event adapter
    • Multiple event formats produced
  • Consumer-side architectures
    • Multiple event formats through adapter
    • Consumer-side adapters
    • Multiple event formats consumed
• Acknowledgments
• Use Cases
• Design Decisions
  • Keys, Values and Types
  • Simplified data model
  • Artifacts
• Whitepaper

History

The Events in CI/CD Workstream was originally formed by the CDF Interoperability Special Interest Group with the mission to Standardize events to be used in a CI/CD process. The workstream later evolved into Event Special Interest Group, which defined the initial vocabulary for CI/CD events, developed a golang SDK and a first proof of concept which involved Tekton and keptn.

The initial vocabulary then became CDEvents, a new standalone CDF incubated project.

Design reflections

How does CDEvents enable tools to communicate in an interoperable way?

By creating a language, we define how tools and services communicate with each other about occurrences in a CI/CD system. As this language does not tie to a specific tool it serves a neutral ground for communication.

Using this language we define a set of events with purpose and semantic meaning. With such a well-defined language, tools know what events to send, and receivers know how to interpret the information received. This enables tools to have a common understanding of the information sent in the events.

The language enables creating an ecosystem of tools for monitoring, tracing, measuring, and orchestrating using our events without having to write a “plugin” for every tool.

Why use events?

Reading from the CloudEvents primer - design goals

The goal of the CloudEvents specification is to define interoperability of event systems that allow services to produce or consume events, where the producer and consumer can be developed and deployed independently. A producer can generate events before a consumer is listening, and a consumer can express an interest in an event or class of events that is not yet being produced.

We believe that using events will lead to a more decoupled systems with services and tools developed and deployed independently. This makes us agnostic of the underlying infrastructure

Why not point-to-point communication?

We believe that using integrations based on point-to-point communication will create a system that will:

• Not scale - when trying to add new consumers or producers each tool have to make an update
• Create a coupled architecture - using point-to-point communication creates a tightly intertwined architecture difficult to expand and monitor.

Declarative vs. imperative events

CDEvents are declarative events. With “declarative” we refer to event through which the producer sends information about an occurrence, but it does not know how the event will be used on the receiving side or even who will receive it.

With imperative events we refer to events that are sent with the intent of triggering a specific reaction, like “start a pipeline” or “deploy an application”. CDEvents do not support imperative events today; the specification may include imperative events in future to foster interoperability in systems that rely on imperative events today.

Imperative events create coupling between producer and consumer as they typically require some form of acknowledgement to be send back by the consumer of the original event back to the producer. Imperative events are useful to implement workflows where the orchestration logic is centrally managed by a single component.

A behavior similar to that of imperative events can be achieved by moving part of the business logic to an adapter that listens for specific declarative events and decides based on a set of policy to trigger actions in a downstream system, similarly to what is described in the receiving adapters scenario.

Relations to CloudEvents

CDEvents defines a specification that provides a set of JSON object schemas (one for each event type, covering mandatory and optional attributes etc.)

When used with CloudEvents, CDEvents passes the JSON schema via the dataschema attribute and provide the corresponding JSON object through the data attribute.

CDEvents aims to use existing CloudEvents extension attributes (e.g. partitionkey from the Partitioning extension) before defining its own extensions. When no appropriate extension attributes exists, CDEvents aims to make an official CloudEvents extension for the CloudEvents specification and listed with other documented extensions.

Versioning

The CDEvents specification and events are versioned independently, both following the principle of semantic versioning.

Versioning of CDEvents

Individual CDEvents are versioned using semantic versioning, with a major.minor.patch format of the version.

Backward compatible changes are changes that allow existing consumers to parse messages with a newer version, have access to the same data as before, as long the extra fields are ignored. Broadening the accepted values for a property is a backward incompatible change, as the consumer may not be prepared to manage the new format of value.

Note that this means that consumers SHOULD be prepared to handle (and disregard) unrecognized properties in higher minor versions than they are familiar with.

• Major versions (e.g. 0.3.1 -> 1.0.0): backward incompatible changes to events. Renamed, moved or removed fields requires a new major version.

• Minor versions (e.g. 0.1.2 -> 0.2.0): backward compatible changes to events that involve a structural change in the schema. A new field is added, a copy of an existing field is added and the old location deprecated, or a new

• Patch versions (e.g. 0.1.0 -> 0.1.1): backward compatible changes to events that do not involve any structural change in the schema, for instance narrowing the accepted values for a property

While the specification of an event is work in progress, its version is tagged with an extra -draft at the end.

The version of an event is included in its type. This allows for easy filtering of events of a specific version, by looking at a single field in the context. Examples of full event versions are:

• dev.cdevents.build.queued.0.1.0-draft
• dev.cdevents.environment.deleted.0.1.0

Versioning of the CDEvents specification

The overall CDEvents specification is versioned using semantic versioning, with a major.minor.patch format of the version. The specification version is associated to a git version (tag) in the cdevents/spec repository, in the format vMajor.Minor.Patch.

• A specification that includes only cosmetic fixes is identified by a change in the patch version, for instance 0.1.0 -> 0.1.1

• A specification that includes only backwards compatible change is identified by a change in the minor version, for instance 0.1.3 -> 0.2.0

• A specification that includes at least one backward incompatible change, is identified by a change in the major version, for instance 0.1.2 -> 2.0.0

While a version of the specification is work in progress, its version is tagged with an extra -draft at the end, for instance 0.1.0-draft.

Development of a new version

The specification on the main branch is versioned with the number of the next version followed by a -draft. If any event is modified, its version is changed accordingly, followed by a -draft as well.

Once a specification is ready for release, its number if updated, the event versions are finalized (-draft is removed), schemas are updated and a git tag is created for this last commit.

Extending CDEvents

The CDEvents specification is designed to evolve over time, to accommodate the need of CDEvents users and cover a growing number of use cases. In all cases we prefer backward compatible changes, which could be new fields in existing events or new event types. Versioning of messages is used for producers to validate messages before they are sent, and for consumer to know how to parse them.

Adding new data to CDEvents

If the data model of a CDEvent is not sufficient, events producers may choose to pass extra data through the customData field. Using customData can be an effective interim step, as it’s easy to implement and can be used to help the migration process from existing events to CDEvents.

In most cases though customData should not be considered as a permanent solution, since consumers don’t know how to process this extra data, unless they implement producer specific logic and sacrifice part of the interoperability benefit of using CDEvents.

Adding a new field to an existing CDEvent type is considered a backward compatible change - see the versioning for more details. Aspects to consider when proposing a new field are:

• is the field generally useful to the CD community? Data that is unique to a single platform is likely to be rejected
• what are the use cases where this field will be used?
• what is the format for the new field? Please be as specific as possible
• what is the name of the new field? Check the SIG interoperability vocabulary if a standard name exists. If not propose the new field name for the vocabulary as well.

Adding new event types

If a new event type is needed, it’s good practice to contribute the new type into the CDEvents specification. Custom events can be used, but they should not use the “dev.cdevents” namespace for their type.

Custom events are not interoperable, so existing CDEvents consumers won’t be able to handle them. Introducing a custom event is simple enough on the producer side but it doesn’t scale well with the number of consumers.

Adding a new event to an existing CDEvents bucket is a backward compatible change. Aspects to consider when proposing a new event type are:

• is the event generally useful to the CD community? Events that are very specific to a single platform are likely to be rejected. If the event represents a functionality that is currently only implemented in one platform, but nonetheless generally useful, it can still be introduced in CDEvents
• what are the use cases where this event will be used?
• what are the sources of these events?
• if the event includes a new kind of subject, what is the data model of the subject? What is the format of its ID? Please be as specific as possible
• what is the name of the new type? Check the SIG interoperability vocabulary if a standard name exists. If not consider proposing the new field name for the vocabulary as well.

Adopting CDEvents

When adopting CDEvents, producers and consumers alike may adopt different strategies to support existing event producers and consumers that want to consider existing messaging systems, formats and event producers and consumers that are in place. CDEvents is a new specification, but neither CloudEvents nor events in general are a new idea, and several tools may already be using events or webhooks with a tool specific data model.

Below we consider a set of common scenarios and how CDEvents may be incrementally introduced in an existing system.

Producer-side architectures

In the first three scenarios, CDEvents are introduced in the producer side, either directly in the tool or through some external component.

External event producer

If a tool does not produce events, it may be possible to use an external component to “watch” a tool output (for instance logs) and produce CDEvents.

If the output does not contain all information required for the events, this limitation can be worked-around by adding the missing data in the tool output.

This solution may be brittle, because the tool output may not be a stable interface for the tool, and it may change over time without notice.

This approach is certainly valid to build a proof-of-concept or to experiment with events in an existing environment.

If the output of the tool is structured and part of the tool API, this may also be adopted as a permanent solution, to keep separation of concerns between the tool itself and the process of generating events.

External event adapter

If a tool does produce events, it may be possible to use an external adapter component to convert the existing events into CDEvents.

Similar to the previous case, incoming events may be missing data required by CDEvents. If the events come from a tool that we do not control, we cannot alter the content of the events, so we may request the tool maintainers to either add the extra data or, like in the next scenario, start producing CDEvents natively.

Multiple event formats produced

A tool may start producing CDEvents natively. If the tool previously produced events, some consumers may expect the pre-existing event format. This can be solved on the producer side by sending both format of events in parallel.

In some cases it may be possible to use a single broker for both event types, for instance if both formats are CloudEvents based.

Consumer-side architectures

Typically it won’t be possible for all existing event consumers to switch to CDEvents at the same time. The following scenarios show how an incremental approach can be used to migrate consumers towards CDEvents gradually.

Multiple event formats through adapter

In a variation of the previously mentioned producer-side architectures, the tool produces only one format of events, which is sent to the broker. The adapter subscribes to the events, converts them and publishes them back to the broker. Consumer may then subscribe to the type of events that they prefer.

With this architecture, the adapter may even be able to convert messages from different tools, instead of just one.

Consumer-side adapters

In this scenario, the tool and some consumers use CDEvents. New consumers are added that do not understand CDEvents, or that do not support events in general. An adapter can be used to convert a CDEvent into the consumer specific format or to extract data from a CDEvent and use it to invoke an API for the receiving side.

Multiple event formats consumed

In this scenario, a new tool is added that produces CDEvents. An existing consumer wants to benefit from existing events as well as the events from the new tool.

A single consumer may receive events from heterogenous sources.

Use Cases

There are two root use cases that we are considering:

• Interoperability through CDEvents: In this use case, platforms from the CD landscape either produce or consume CDEvents. On the producing side, a system broadcasts that certain value has been produced, like a code change, an artifact or a test result. On the consumer-side, a system takes an action that takes advantage of that value that has been produced.

• Observability & Metrics: In this use case, platforms from the CD landscape produce CDEvents that describe the start and end of parts of an end of end CD workflow, for instance build started and finished, artifact packaged and published and deployment started and finished. We want to visualize the end to end CD workflow, for instance from a change being written, through its build, test, release, deployment and possibly rollback in case a remediation is required. To achieve that, events are sent to an event router and collected by a pipeline visualization application, that uses the information in the events to correlate them with each other and build an end to end view. With the same events, we want to measure DevOps performance as well. The same events can be used to track different metrics over time, to be visualized through a dashboard. The current events provide enough data to calculate two of the four DORA DevOps metrics:

  • Lead time for changes: the amount of time it takes a commit to get into production
  • Deployment frequency: how often an organization successfully releases to production

Terminology

The CDF Interoperability Special Interest Group has produced a table of the terms used by different CI/CD tools and how they relate to each other. The SIG Interoperability is also working on distilling a recommended shared terminology. CDEvents strives to adopt to the shared terminology and collaborate with the SIG Interoperability.

Work to align terms to those identified by the SIG Interoperability will continue in upcoming CDEvents releases.

Design Decisions

Keys, Values and Types

The CDEvents specification defines event types, keys and, for ENUM types, values.

Event types are defined as all lowercase, separated by dots. The first part of each type is always “dev.cdevents” which is the reverse DNS domain of the CDEvents project.

Keys and ENUM values are always written in lowerCamelCase for readability purposes.

Simplified data model

In the initial version of CDEvents we tackled a simple scenario in which each artifact is built from a single repository and each service is deployed from a single artifact.

This data model is somewhat limited, but is has allowed us to put more focus on the overall structure of the protocol in the first release.

We plan to extend the data model to support more complex scenarios in upcoming releases.

Artifacts

The specification has chosen for v0.1.0 to adopt package-urls (or purls) as the format for any artifact identifier included in the spec. Purls provide a consistent format for artifact identifiers across different package types.

CDEvents wishes for a format that can be used to reference to an artifact, or package, that is independent from the hosting storage, which is a property which purls satisfy for several artifact types.

Whitepaper

The CDEvents whitepaper has been originally published on June 7, 2022 on the CDF blog. It is intended for an audience of DevOps Engineers, Project Managers/Directors, CTOs, and Cloud Architects who are interested in learning more about CDEvents, why it was created and its mission.

Acknowledgments

The initial structure of the CDEvents specification format was based on the specification of the CloudEvents project.

2 -

CDEvents

Abstract

CDEvents is a common specification for Continuous Delivery events.

Table of Contents

• Overview
• Notations and Terminology
  • Notational Conventions
  • Terminology
    • Event
    • Subject
    • Predicate
  • Types
• CDEvent context
  • REQUIRED Context Attributes
    • id (context)
    • type (context)
    • source (context)
    • timestamp
    • version
  • Context example
• CDEvent subject
  • REQUIRED Subject Attributes
    • id (subject)
    • content
  • OPTIONAL Subject Attributes
    • source (subject)
    • type (subject)
  • Subject example
• CDEvents custom data
  • OPTIONAL Custom Data attributes
    • customData
    • customDataContentType
  • Examples
    • JSON Data
    • Generic Data
• Vocabulary
  • Vocabulary Stages

Overview

Each CDEvent is structured into two mandatory parts:

• The context: its structure is common to all CDEvents
• The subject: part of its root structure is common to all CDEvents, some of its content may vary from event to event, as described in the vocabulary

plus two optional attributes customData and customDataEncoding, that host CDEvents custom data.

The specification is structured in two main parts:

• This document describes the part of the spec that are common to all events:

  • The context, made of mandatory and optional attributes
  • The common part of the subject
  • How to include custom / additional data in a CDEvent

• The vocabulary describes event types, with their event specific mandatory and optional attributes. These attributes are all located in the subject object within the event. The vocabulary is organized in stages, each specified in a dedicated document in the spec.

For an introduction see the CDEvents README and for more background information please see our CDEvents primer.

Notations and Terminology

Notational Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

For clarity, when a feature is marked as “OPTIONAL” this means that it is OPTIONAL for both the Producer and Consumer of a message to support that feature. In other words, a producer can choose to include that feature in a message if it wants, and a consumer can choose to support that feature if it wants. A consumer that does not support that feature will then silently ignore that part of the message. The producer needs to be prepared for the situation where a consumer ignores that feature. An Intermediary SHOULD forward OPTIONAL attributes.

Terminology

Note: CDEvents adopts, wherever applicable, the terminology used by CloudEvents. Specifically, the following terms are borrowed from the CloudEvents spec:

• Occurrence
• Producer
• Source
• Consumer
• Intermediary

The CDEvents specification additionally defines the following terms:

Event

An “event” is a data record expressing an occurrence and its context. Events are routed from an event producer (the source) to interested event consumers. The routing can be performed based on information contained in the event, but an event will not identify a specific routing destination.

Subject

The “subject” is the entity with which the occurrence in a software system is concerned. For instance when a software build is started, the build is the subject of the occurrence, or when a service is deployed, the subject is the service. Subjects have a list of attributes associated, defined in the vocabulary. Subjects belong to two main categories:

• long running, which stay in a running state until they’re purposely stopped or encounter a failure or a condition that prevents them from running - for example a service, an environment, an artifact or a source change
• run to completion, which independently stop after they accomplished (or failed to) a specific task, or encounter a failure or a condition that prevents them from continuing - for example a task run, a build or a test

Predicate

A “predicate” is what happened to a subject in an occurrence. For instance in case of a software build, started is a valid predicate in the occurrence, or in case of a service, deployed in a valid predicate. Valid predicate are defined in the vocabulary.

Types

Attributes in CDEvents are defined with as typed. We use a the types system defined by the CloudEvents project, plus some CDEvents specific types

• Enum: an attribute of type String, constrained to a fixed set of options

• List: a list of values of the same type

• Object: a map of (key, value) tuples

  • Keys are of type String. Valid keys can be defined by this spec
  • Values can be any of the other kind
  • An object key is referred to as an “attribute”

• Purl: a string in package-url format

  Object key names are by convention defined in CamelCase.

CDEvent context

REQUIRED Context Attributes

The following context attributes are REQUIRED to be present in all the Events defined in the vocabulary:

id (context)

• Type: String

• Description: Identifier for an event. Subsequent delivery attempts of the same event MAY share the same id. This attribute matches the syntax and semantics of the id attribute of CloudEvents.

• Constraints:

  • REQUIRED
  • MUST be a non-empty string
  • MUST be unique within the given source (in the scope of the producer)

• Examples:

  • A UUID version 4

type (context)

• Type: String

• Description: defines the type of event, as combination of a subject, predicate and version. Valid event types are defined in the vocabulary. All event types should be prefixed with dev.cdevents.. One occurrence may have multiple events associated, as long as they have different event types. Versions are semantic in the major.minor.patch format. For more details about versions see the the see versioning documentation.

• Constraints:

  • REQUIRED
  • MUST be defined in the vocabulary

• Examples:

  • dev.cdevents.taskrun.started
  • dev.cdevents.environment.created
  • dev.cdevents.<subject>.<predicate>

source (context)

• Type: URI-Reference

• Description: defines the context in which an event happened. The main purpose of the source is to provide global uniqueness for source + id.

  The source MAY identify a single producer or a group of producer that belong to the same application.

  When selecting the format for the source, it may be useful to think about how clients may use it. Using the root use cases as reference:

  • A client may want to react only to events sent by a specific service, like the instance of Tekton that runs in a specific cluster or the instance of Jenkins managed by team X
  • A client may want to collate all events coming from a specific source for monitoring, observability or visualization purposes

• Constraints:

  • REQUIRED
  • MUST be a non-empty URI-reference
  • An absolute URI is RECOMMENDED

• Examples:

  • If there is a single “context” (cloud, cluster or platform of some kind)

    • /tekton
    • https://www.jenkins.io/

  • If there are multiple “contexts”:

    • /cloud1/spinnaker-A
    • /cluster2/keptn-A
    • /teamX/knative-1

timestamp

• Type: timestamp

• Description: defines the time of the occurrence. When the time of the occurrence is not available, the time when the event was produced MAY be used.

  In case the transport layer should require a re-transmission of the event, the timestamp SHOULD NOT be updated, i.e. it should be the same for the same source + id combination.

• Constraints:

  • REQUIRED
  • MUST adhere to the format specified in RFC 3339

version

• Type: String

• Description: The version of the CDEvents specification which the event uses. This enables the interpretation of the context. Compliant event producers MUST use a value of 0.1.0 when referring to this version of the specification. For more details see versioning.

• Constraints:

  • REQUIRED
  • MUST be a non-empty string

Context example

This is an example of a full CDEvent context, rendered in JSON format:

{
    "context": {
    "version" : "0.1.0",
    "id" : "A234-1234-1234",
    "source" : "/staging/tekton/",
    "type" : "dev.cdevents.taskrun.started",
    "timestamp" : "2018-04-05T17:31:00Z"
  }
}

CDEvent subject

REQUIRED Subject Attributes

The following subject attributes are REQUIRED to be present in all the event defined in the vocabulary:

id (subject)

• Type: String

• Description: Identifier for a subject. Subsequent events associated to the same subject MUST use the same subject id.

• Constraints:

  • REQUIRED
  • MUST be a non-empty string
  • MUST be unique within the given source (in the scope of the producer)

• Examples:

  • A UUID version 4

content

• Type: Object

• Description: This provides all the relevant details of the content. The format of the content depends on the event type. All attributes in the subject content, REQUIRED and OPTIONAL ones, MUST comply with the specification from the vocabulary. The content may be empty.

• Constraints:

  • REQUIRED

• Example:

  • Considering the event type dev.cdevents.taskrun.started, an example of subject, serialized as JSON, is:

        "content" : {
          "task": "my-task",
          "url": "/apis/tekton.dev/v1beta1/namespaces/default/taskruns/my-taskrun-123"
        }
    

OPTIONAL Subject Attributes

source (subject)

• Type: URI-Reference

• Description: defines the context in which the subject originated. In most cases the source of the subject matches the source of the event. This field should be used only in cases where the source of the subject is different from the source of the event.

  The format and semantic of the subject source are the same of those of the context source.

type (subject)

• Type: Enum

• Description: A string defined in the vocabulary that identifies the type of subject.

• Constraints:

  • REQUIRED when content is not empty

Subject example

The following example shows context and subject together, rendered as JSON.

{
   "context": {
      "version" : "0.1.0",
      "id" : "A234-1234-1234",
      "source" : "/staging/tekton/",
      "type" : "dev.cdevents.taskrun.started",
      "timestamp" : "2018-04-05T17:31:00Z"
   },
   "subject" : {
      "id": "my-taskrun-123",
      "type": "taskRun",
      "content": {
         "task": "my-task",
         "url": "/apis/tekton.dev/v1beta1/namespaces/default/taskruns/my-taskrun-123",
         "pipelineRun": {
            "id": "my-distributed-pipelinerun",
            "source": "/tenant1/tekton/"
         }
      }
   }
}

CDEvents custom data

The customData and customDataContentType fields can be used to carry additional data in CDEvents.

OPTIONAL Custom Data attributes

customData

• Type: This specification does not place any restriction on the type of this information.

• Description: custom data. The content of the customData field is not specified in CDEvent and typically require tool specific knowledge to be parsed.

• Constraints:

  • OPTIONAL

• Examples:

  • {"mydata1": "myvalue1"}
  • "VGhlIHZvY2FidWxhcnkgZGVmaW5lcyAqZXZlbnQgdHlwZXMqLCB3aGljaCBhcmUgbWFkZSBvZiAqc3ViamVjdHMqCg=="

customDataContentType

The customDataContentType is modelled after the CloudEvents datacontenttype.

• Type: String

• Description: Content type of customData value. This attribute enables data to carry any type of content, whereby format and encoding might differ from that of the chosen event format. For example, an event rendered using the CloudEvents format might carry an XML payload in data, and the consumer is informed by this attribute being set to “application/xml”. The rules for how data content is rendered for different customDataContentType values are defined in the specific binding specification

• Default value: “application/json”

• Constraints:

  • OPTIONAL
  • If present, MUST adhere to the format specified in RFC 2046

Examples

JSON Data

Data with the default “application/json” content-type can be included directly in the customData field, as in the following example:

{
  "context": {
    (...)
  },
  "subject" : {
    (...)
  },
  "customData": {
    "mydata1": {
      "f1": "f1",
      "f2": "f2"
    },
    "mydata2": "myvalue1"
  }
}

Generic Data

Generic (non-JSON) data, must be base64 encoded:

{
  "context": {
    (...)
  },
  "subject" : {
    (...)
  },
  "customData": "PGRhdGE+VkdobElIWnZZMkZpZFd4aGNua2daR1ZtYVc1bGN5QXFaWFpsYm5RZ2RIbHdaWE1xTENCM2FHbGphQ0JoY21VZ2JXRmtaU0J2WmlBcWMzVmlhbVZqZEhNcUNnPT08L2RhdGE+Cg==",
  "customDataContentType": "application/xml"
}

Vocabulary

The vocabulary defines event types, which are made of subjects, and predicates. An example of subject is a build. The build can be started or finished, which are the predicates. The build is of type Object and has several attributes associated; the event type schema defines which ones are mandatory and which ones are optional. Subjects can represent the core context of an event, but may also be referenced to in other areas of the protocol.

The subjects are grouped, to help browsing the spec, in different stages, which are associated to different parts of a Continuous Delivery process where they are expected to be produced.

These subjects, with their associated predicates and attributes, are agnostic from any specific tool and are designed to fit a wide range of scenarios. The CDEvents project collaborates with the SIG Interoperability to identify a the common terminology to be used and how it maps to different terms in different platforms.

Vocabulary Stages

The vocabulary is organized in stages, each specified in a dedicated document in the spec:

• Core: includes core events related to core activities and orchestration that needs to exist to be able to deterministically and continuously being able to delivery software to users.
• Source Code Version Control: Events emitted by changes in source code or by the creation, modification or deletion of new repositories that hold source code.
• Continuous Integration: includes events related to building, testings, packaging and releasing software artifacts, usually binaries.
• Continuous Deployment: include events related with environments where the artifacts produced by the integration pipelines actually run. These are usually services running in a specific environment (dev, QA, production), or embedded software running in a specific hardware.

The grouping may serve in future as a reference for different CDEvents compliance profiles, which can be supported individually by implementing platforms.

3 -

Continuous Delivery Core Events

Continuous Delivery Core Events include the subjects and predicates related to orchestration of execution required to deterministically and continuously delivery software to users. Core events are at the lower level of abstraction in the dictionary: they describe the status of an execution, but they don’t include any semantic about the function of the execution itself. These events are generated by pipeline orchestration engines.

Subjects

In the context of Continuous Delivery, a pipeline is the definition of a set of tasks that needs to be performed to build, test, package, release and deploy software artifacts. The definition of pipelines and tasks is an authoring process, and has no event associated to it. CDEvents identifies two subjects, pipelineRun and taskRun, which are the runtime counterparts of pipelines and tasks.

pipelineRun

A pipeline can be instantiated multiple times, for example to build different versions of the same artifact. We are referring to this instance as pipelineRun. It will have a unique id and it will help us to track the build and release progress on a particular software artifact.

taskRun

Pipelines are composed by as a set of Tasks to be performed, like performing a build, running some tests, publishing an artifact. A taskRun is an instance of a Task, typically part of a pipeline. If a Pipeline is composed by a single Task, the execution of pipelineRun MUST generate both the pipelineRun and taskRun events. Some systems may support execution of Tasks without a Pipeline associated, in which case it is acceptable to generate only taskRun events.

Events

pipelineRun queued

Due the dynamic nature of Pipelines, most of actual work needs to be queued to happen in a distributed way, hence queued events are added. Adopters can choose to ignore these events if they don’t apply to their use cases.

• Event Type: dev.cdevents.pipelinerun.queued.0.1.0
• Predicate: queued
• Subject: pipelineRun

pipelineRun Started

A pipelineRun has started and it is running.

• Event Type: dev.cdevents.pipelinerun.started.0.1.0
• Predicate: started
• Subject: pipelineRun

pipelineRun Finished

A pipelineRun has finished, successfully or not.

• Event Type: dev.cdevents.pipelinerun.finished.0.1.0
• Predicate: finished
• Subject: pipelineRun

taskRun Started

A taskRun has started and it is running.

• Event Type: dev.cdevents.taskrun.started.0.1.0
• Predicate: started
• Subject: taskRun

taskRun Finished

A taskRun has finished, successfully or not.

• Event Type: dev.cdevents.taskrun.finished.0.1.0
• Predicate: finished
• Subject: taskRun

4 -

Source Code Version Control Events

Source Code Version Control events includes the subjects and predicates related to changes in Source Code repositories that are relevant from a Continuous Delivery perspective.

Subjects

This specification defines two subjects in this stage: repository and change. Events associated with these subjects are triggered by actions performed by software developers or bots that provide useful automation for software developers.

Each repository can emit events related with proposed source code changes. Each change can include a single or multiple commits that can also be tracked.

repository

An SCM repository is identified by a name, an owner which can be a user or an organization, a url which is where the repository is hosted and optionally a viewUrl, which is a web location for humans to browse the content of the repository.

branch

A branch in an SCM repository is identified by its id.

change

A change identifies a proposed set of changes to the content of a repository. The usual lifecycle of a change The data model for changes is not defined yet.

Events

repository created

A new Source Code Repository was created to host source code for a project.

• Event Type: dev.cdevents.repository.created.0.1.0
• Predicate: created
• Subject: repository

repository modified

A Source Code Repository modified some of its attributes, like location, or owner.

• Event Type: dev.cdevents.repository.modified.0.1.0
• Predicate: modified
• Subject: repository

repository deleted

• Event Type: dev.cdevents.repository.deleted.0.1.0
• Predicate: modified
• Subject: repository

branch created

A branch inside the Repository was created.

• Event Type: dev.cdevents.branch.created.0.1.0
• Predicate: created
• Subject: branch

branch deleted

A branch inside the Repository was deleted.

• Event Type: dev.cdevents.branch.deleted.0.1.0
• Predicate: deleted
• Subject: branch

change created

A source code change was created and submitted to a repository specific branch. Examples: PullRequest sent to Github, MergeRequest sent to Gitlab, Change created in Gerrit.

• Event Type: dev.cdevents.change.created.0.1.0
• Predicate: created
• Subject: change

change reviewed

Someone (user) or an automated system submitted an review to the source code change. A user or an automated system needs to be in charge of understanding how many approvals/rejections are needed for this change to be merged or rejected. The review event needs to include if the change is approved by the reviewer, more changes are needed or if the change is rejected.

• Event Type: dev.cdevents.change.reviewed.0.1.0
• Predicate: reviewed
• Subject: change

change merged

A change is merged to the target branch where it was submitted.

• Event Type: dev.cdevents.change.merged.0.1.0
• Predicate: merged
• Subject: change

change abandoned

A tool or a user decides that the change has been inactive for a while and it can be considered abandoned.

• Event Type: dev.cdevents.change.abandoned.0.1.0
• Predicate: abandoned
• Subject: change

change updated

A Change has been updated, for example a new commit is added or removed from an existing Change.

• Event Type: dev.cdevents.change.updated.0.1.0
• Predicate: updated
• Subject: change

5 -

Continuous Integration Events

Continuous Integration (CI) events include the subject and predicates related to CI activities such as building software, producing artifacts and running tests.

Subjects

This specification defines three subjects in this stage: builds, artifacts and tests. Events associated with these subjects are typically generated either by a CI system that orchestrates the process or by a specific build or test tool directly. Some artifact events may be generated by the system that stores the artifact as well.

build

A build is a process that uses a recipe to produce an artifact from source code.

Note: The data model for builds, apart from id and source, only includes the identifier of the artifact produced by the build. The inputs to the build process are not specified yet.

testCase

A testCase is a process that performs a test against an input software artifact of some kind, for instance source code, a binary, a container image or else. A testCase is the smallest unit of testing that the user wants to track. testCases are executed, and testSuites are for grouping purposes. For this reason, testCases can be queued.

Note: The data model for testCase only includes id and source, inputs and outputs of the process are not specified yet, as well as the relation to testSuite.

testSuite

A testSuite represents a set of one or more testCases.

Note: The data model for testSuite only includes id and source, inputs and outputs of the process are not specified yet, as well as the relation to testCase.

artifact

An artifact is usually produced as output of a build process. Events need to be generated to indicate that an artifact has been packaged and released for others to use. These events can be produced by the artifact producer or by the artifact storage system.

Events

build queued

This event represents a Build task that has been queued; this build process usually is in charge of producing a binary from source code.

• Event Type: dev.cdevents.build.queued.0.1.0
• Predicate: queued
• Subject: build

build started

This event represents a Build task that has been started; this build process usually is in charge of producing a binary from source code.

• Event Type: dev.cdevents.build.started.0.1.0
• Predicate: started
• Subject: build

build finished

This event represents a Build task that has finished. This event will eventually contain the finished status, success, error or failure

• Event Type: dev.cdevents.build.finished.0.1.0
• Predicate: finished
• Subject: build

testCase queued

This event represents a Test task that has been queued, and it is waiting to be started.

• Event Type: dev.cdevents.testcase.queued.0.1.0
• Predicate: queued
• Subject: testCase

testCase started

This event represents a Test task that has started.

• Event Type: dev.cdevents.testcase.started.0.1.0
• Predicate: started
• Subject: testCase

testCase finished

This event represents a Test task that has finished. This event will eventually contain the finished status: success, error or failure.

• Event Type: dev.cdevents.testcase.finished.0.1.0
• Predicate: finished
• Subject: testCase

testSuite started

This event represents a Test suite that has been started.

• Event Type: dev.cdevents.testsuite.started.0.1.0
• Predicate: started
• Subject: testSuite

testSuite finished

This event represents a Test suite that has has finished, the event will contain the finished status: success, error or failure.

• Event Type: dev.cdevents.testsuite.finished.0.1.0
• Predicate: finished
• Subject: testSuite

artifact packaged

The event represents an artifact that has been packaged for distribution; this artifact is now versioned with a fixed version.

• Event Type: dev.cdevents.artifact.packaged.0.1.0
• Predicate: packaged
• Subject: artifact

artifact published

The event represents an artifact that has been published and it can be advertised for others to use.

• Event Type: dev.cdevents.artifact.published.0.1.0
• Predicate: published
• Subject: artifact

6 -

Continuous Deployment Events

Continuous Deployment (CD) events are related to continuos deployment pipelines and their target environments. These events can be emitted by environments to report where software artifacts such as services, binaries, daemons, jobs or embedded software are running.

Subjects

This specification defines two subjects in this stage: environment and service. The term service is used to represent a running Artifact. A service can represent a binary that is running, a daemon, an application, a docker container. The term environment represent any platform which has all the means to run a service.

environment

An environment is a platform which may run a service.

service

A service can represent for example a binary that is running, a daemon, an application or a docker container.

Events

environment created

This event represents an environment that has been created. Such an environment can be used to deploy services in.

• Event Type: dev.cdevents.environment.created.0.1-draft
• Predicate: created
• Subject: environment

environment modified

This event represents an environment that has been modified.

• Event Type: dev.cdevents.environment.modified.0.1-draft
• Predicate: modified
• Subject: environment

environment deleted

This event represents an environment that has been deleted.```

• Event Type: dev.cdevents.environment.deleted.0.1-draft
• Predicate: deleted
• Subject: environment

service deployed

This event represents a new instance of a service that has been deployed

• Event Type: dev.cdevents.service.deployed.0.1-draft
• Predicate: deployed
• Subject: service

service upgraded

This event represents an existing instance of a service that has been upgraded to a new version

• Event Type: dev.cdevents.service.upgraded.0.1-draft
• Predicate: upgraded
• Subject: service

service rolledback

This event represents an existing instance of a service that has been rolled back to a previous version

• Event Type: dev.cdevents.service.rolledback.0.1-draft
• Predicate: rolledback
• Subject: service

service removed

This event represents the removal of a previously deployed service instance and is thus not longer present in the specified environment

• Event Type: dev.cdevents.service.removed.0.1-draft
• Predicate: removed
• Subject: service

service published

This event represents an existing instance of a service that has an accessible URL for users to interact with it. This event can be used to let other tools know that the service is ready and also available for consumption.

• Event Type: dev.cdevents.service.published.0.1-draft
• Predicate: published
• Subject: service

7 -

CloudEvents Binding for CDEvents

Abstract

The CloudEvents Binding for CDEvents defines how CDEvents are mapped to CloudEvents headers and body.

Table Of Contents

• CloudEvents Context
  • specversion
  • id
  • source
  • type
  • subject
  • time
  • datacontenttype
  • dataschema
• CloudEvents Data
  • Examples

CloudEvents Context

The CloudEvents context is built by the event producer using some of the data from the CDEvents context.

specversion

The CloudEvents specversion MUST be set to 1.0.

id

The CloudEvents id MUST be set to the CDEvents id.

source

The CloudEvents source MUST be set to the CDEvents source.

type

The CloudEvents type MUST be set to the type of the CDEvent.

subject

The CloudEvents subject MUST be set to the subject id of the CDEvent. Note: since the subject is mandatory in CDEvents, the subject in the CloudEvents format will always be set - even if it’s not mandated by the CloudEvents specification.

time

The CloudEvents time MUST be set to the timestamp of the CDEvent. The CloudEvents specification allows for time to be set to either the current time or the time of the occurrence, but it requires all producers to be chose the same option. CDEvents requires all producers to use the timestamp from the CDEvent to meet the CloudEvents specification.

datacontenttype

The CloudEvents datacontenttype is optional, its use depends on the specific CloudEvents binding and mode in use. See the event data section for more details.

dataschema

The CloudEvents dataschema is MAY be set to a URL that points to the event data schema included in this specification.

CloudEvents Data

The content and format of the event data depends on the specific CloudEvents binding in use. All the examples, unless otherwise stated, refer to theHTTP binding in binary content mode. In this format, the CloudEvents context is stored in HTTP headers.

The CloudEvents Event Data MUST include the full CDEvents, i.e. context, subject and any custom data, rendered as JSON in the format specified by the schema for the event type.

Custom data of type “application/json” MUST be embedded as is in the customData field. Data with any other content-type MUST be base64 encoded and set as value for the customData field.

In CloudEvents HTTP binary mode, the Content-Type HTTP header MUST be set to application/json. In CloudEvents HTTP structured mode, the same information is carried in the CloudEvents context field datacontenttype.

Examples

Full example of a CDEvents transported through a CloudEvent in HTTP binary mode:

POST /sink HTTP/1.1
Host: cdevents.example.com
ce-specversion: 1.0
ce-type: dev.cdevents.taskrun.started.0.1-draft
ce-time: 2018-04-05T17:31:00Z
ce-id: A234-1234-1234
ce-source: /staging/tekton/
ce-subject: /namespace/taskrun-123
Content-Type: application/json; charset=utf-8
Content-Length: nnnn

{
   "context": {
      "version" : "0.1.0",
      "id" : "A234-1234-1234",
      "source" : "/staging/tekton/",
      "type" : "dev.cdevents.taskrun.started",
      "timestamp" : "2018-04-05T17:31:00Z",
   }
   "subject" : {
      "id": "/namespace/taskrun-123",
      "type": "taskRun",
      "content": {
         "task": "my-task",
         "url": "/apis/tekton.dev/v1beta1/namespaces/default/taskruns/my-taskrun-123"
         "pipelineRun": {
            "id": "/somewherelse/pipelinerun-123",
            "source": "/staging/jenkins/"
         }
      }
   }
}

8 -

CDEvents Governance

The governance for the CDEvents project is documented in the community repository.

9 -

CDEvents is a common specification for Continuous Delivery events, enabling interoperability in the complete software production ecosystem.

It’s an incubated project at the Continuous Delivery Foundation (CDF).

Background

In a complex and fast moving CI/CD world with a lot of different tools and platforms that need to communicate with each other interoperability stands as a crucial thing. The maintainer of a CI/CD system needs to swap out tools in short time with little to no stops.

The larger and more complex a CI/CD system becomes, challenges increase in knowing how the tools communicate and what they do.

What we provide

The CDEvents protocol defines a vocabulary of events enabling tools to communicate in an interoperable way.

We extend other efforts such as CloudEvents by introducing purpose and semantics to the event.

By providing an interoperable way of tools to communicate we also provide means to give an overview picture increasing observability, but also to give measuring points for metrics.

CDEvents Specification

The latest release of the specification is v0.1.0, and you can continuously follow the latest updates of the specification on the main branch.

The concepts and ideas that have formed the current specification are outlined in the CDEvents Primer.

CDEvents SDKs

CDEvents is developing as set of SDKs:

• Go
• Python
• Java

Community

How to get involved

Reach out to see what we’re up via:

• slack
• our mailing list
• our working group meetings

Contributing

If you would like to contribute, see our contributing guidelines.

Governance

The project has been started by the CDF SIG Events and is currently governed by a few members of the SIG.

10 -

CDEvents Mission and Roadmap

This document describes the mission of the CDEvents and its overall roadmap for 2022.

Mission & Vision

The mission of CDEvents project is:

Provide interoperability in the continuous delivery ecosystem through a common events protocol

The vision for the CDEvents project is to have CDEvents natively produced and consumed by as many projects and services as possible in the continuous delivery ecosystem, to provide decoupled and scalable integration with minimal or no glue code.

We envision an ecosystem of tools to generate, store, process and visualize CDEvents.

Roadmap

The continuous delivery ecosystem is quite large as it includes tools and services that span from the design of software, through its implementation, build, test, release, deployment and operation.

In 2022 we want to focus on a few key use cases and make sure that we can fully support them with the protocol specification. More specifically:

• Capture our key use cases and design decisions in the CDEvents primer document
• Develop the spec to fully support our key use cases
  • Create our first release v0.1
  • Define the specification versioning and stability policy
  • Define our requirements for a v1.0
• Validate and demonstrate the spec through proofs-of-concept
• Specify and rework the CloudEvents binding, and develop SDKS:
  • Re-create the SDK for the go language
  • Create a new SDK for the python language
• Evolve the project bootstrap governance into a full governance
• Grow the CDEvents community of projects and contributors

The implementation of proofs of concept will require having CDEvents emitted by various platforms which do not support CDEvents yet. Where possible we will work with the community; it is likely we will have to develop producers and consumers of CDEvents that can adapt existing event formats into CDEvents. We will host such reference implementations in the cdevents organization at least until they can find a new home in the target project. These implementations will be useful to identify the mapping between the data model of a specific platform and CDEvents; we can add these mappings to supporting documentation in cdevents organization.