CDEvents Documentation

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

CDEvents specification

1 -

CDEvents Primer - Draft

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.

Table of Contents

• History
• Design reflections
• Relations to CloudEvents
• Acknowledgments
• Use Cases

History

The Events in CI/CD Worksteam 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.

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.

Acknowledgments

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

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 use cases are work in progress - the list is being drafted in a separate document.

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.

2 -

CDEvents - Draft

Note: This is a work-in-progress version and is being worked on by members of the CDEvents project. You are very welcome to join the work and the discussions!

Abstract

CDEvents is a common specification for Continuous Delivery events.

Table of Contents

• Overview
• Notations and Terminology
  • Notational Conventions
  • Terminology
    • Event
    • Subject
    • Predicate
  • Types
• Context
  • REQUIRED Event Attributes
    • id
    • type
    • source
    • timestamp
    • version
    • subject
• Vocabulary
  • Format of subjects
  • Vocabulary Stages

Overview

The specification is structured in two main parts:

• The context, made of mandatory and optional attributes, shared by all events
• The vocabulary, which identifies event types, structures as subjects and predicates

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

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

  Object key names are by convention defined in CamelCase.

Context

REQUIRED Event Attributes

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

id

• 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

• Type: String

• Description: defines the type of event, as combination of a subject and predicate. 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

• Constraints:

  • REQUIRED
  • MUST be defined in the vocabulary

• Examples:

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

source

• 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 draft when referring to this version of the specification.

• Constraints:

  • REQUIRED
  • MUST be a non-empty string

subject

• Type: Object

• Description: This provides all the relevant details of the subject. The format of the subject depends on the event type.

  The attributes available for each subject are defined in the vocabulary. The REQUIRED and OPTIONAL attributes depend on the event type and are specified in the vocabulary.

• Constraints:

  • REQUIRED
  • If present, MUST comply with the spec from the vocabulary.

• Example:

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

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

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.

Format of subjects

All subjects are of type Object and they share a base Object which they may extend:

The ID field is a mandatory in all cases. The source field is only required when a subject does not belong to the source of the event.

For instance, in case of a distributed pipeline, a taskRun subject could belong to a pipelineRun associated to a different source. Example payload in structured mode:

{
   "context": {
      "version" : "draft",
      "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/"
         }
      }
   }
}

Vocabulary Stages

The stages defined are:

• 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

Note: This is a work-in-progress draft version and is being worked on by members of the Events SIG. You are very welcome to join the work and the discussions!

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
• Predicate: queued
• Subject: pipelineRun

pipelineRun Started

A pipelineRun has started and it is running.

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

pipelineRun Finished

A pipelineRun has finished, successfully or not.

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

taskRun Started

A taskRun has started and it is running.

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

taskRun Finished

A taskRun has finished, successfully or not.

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

4 -

Source Code Version Control Events

Note: This is a work-in-progress draft version and is being worked on by members of the Events SIG. You are very welcome to join the work and the discussions!

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.

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
• 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
• Predicate: modified
• Subject: repository

repository deleted

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

repository branch created

A branch inside the Repository was created.

🚧 The branch model is work in progress.

repository branch deleted

A branch inside the Repository was deleted.

🚧 The branch model is work in progress.

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.

🚧 The change model is work in progress.

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.

🚧 The change model is work in progress.

change merged

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

🚧 The change model is work in progress.

change abandoned

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

🚧 The change model is work in progress.

change updated

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

🚧 The change model is work in progress.

5 -

Continuous Deployment Events

Note: This is a work-in-progress draft version and is being worked on by members of the Events SIG. You are very welcome to join the work and the discussions!

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

The term Service is used to represent a running Artifact. This service can represent a binary that is running, a daemon, an application, a docker container, etc. The term Environment represent any platform which has all the means to run a Service.

• Environment Created: an environment has been created and it can be used to deploy Services
• Environment Modified: an environment has been modified, this event advertise the changes made in the environment
• Environment Deleted: an environment has been deleted and cannot longer be used
• Service Deployed: a new instance of the Service has been deployed
• Service Upgraded: an existing instance of a Service has been upgraded to a new version
• Service Rolledback: an existing instance of a Service has been rolledback to a previous version
• Service Removed: an existing instance of a Service has been terminated an it is not longer present in an environment

Continuous Deployment Events MUST include the following attributes:

• Event Type: the type is restricted to include dev.cdevents.__ prefix. For example dev.cdevents.service.upgraded or dev.cdevents.environment.created
• Environment ID: unique identifier for the Environment

Optional attributes:

• Environment Name: user-friendly name for the environment, to be displayed in tools or User Interfaces
• Environment URL: URL to reference where the environment is located

6 -

Continuous Integration Events

Note: This is a work-in-progress draft version and is being worked on by members of the Events SIG. You are very welcome to join the work and the discussions!

These events are related to Continuous Integration(CI) activities. CI usually include activities such as building, testing, packaging and releasing software artifacts.

The following events represent concrete Tasks that are associated with the execution of CI pipelines:

• Build Queued: a Build task has been queued, this build process usually is in charge of producing a binary from source code
• Build Started: a Build task has started
• Build Finished: a Build task has finished, the event will contain the finished status, success, error or failure

The following Test events are defined in two separate categories Test Case and Test Suite. A Test Case is the smallest unit of testing that the user wants to track. A Test Suite is a collection of test case executions and/or other test suite executions. Test Cases executed, and Test Suites are for grouping purposes. For this reason, Test Cases can be queued.

• Test Case Queued: a Test task has been queued, and it is waiting to be started
• Test Case Started: a Test task has started
• Test Case Finished: a Test task has finished, the event will contain the finished status: success, error or failure
• Test Suite Started: a Test Suite has started
• Test Suite Finished: a Test Suite has finished, the event will contain the finished status: success, error or failure

Finally, events needs to be generated for the output of the pipeline such as the artifacts that were packaged and released for others to use.

• Artifact Packaged: an artifact has been packaged for distribution, this artifact is now versioned with a fixed version
• Artifact Published: an artifact has been published and it can be advertised for others to use

CI Events MUST include the following attributes:

• Event Type: the type is restricted to include dev.cdevents.__ prefix. For example dev.cdevents.build.queued or dev.cdevents.artifact.packaged

Optional attributes:

• Artifact Id: the unique identifier of the artifact that the event is referring to.

7 -

CloudEvents Binding for CDEvents - Draft

Abstract

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

Table Of Contents

• Context
  • specversion
  • id
  • source
  • type
  • subject
  • time
  • datacontenttype
  • dataschema
• Event Data
• Example

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.

Events Data

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

Content Modes

This specification defines two content modes for transferring events: structured and binary. The structured mode can be used in all cases, the binary mode may only be used in conjunction with the HTTP CloudEvent binding in binary mode:

Structured Content Mode

In structured content mode, the CloudEvents Event Data MUST include the full CDEvents context rendered as JSON in the format specified by the schema for the event type.

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

Structured Mode Examples

Full example of a CDEvents in structured content mode, 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
ce-time: 2018-04-05T17:31:00Z
ce-id: A234-1234-1234
ce-source: /staging/tekton/
ce-subject: /namespace/taskrun-123
Content-Type: application/cdevents+json; charset=utf-8
Content-Length: nnnn

{
   "context": {
      "version" : "draft",
      "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/"
         }
      }
   }
}

Binary Content Mode

TBD

Binary Mode Examples

TBD

8 -

CDEvents Bootstrap Governance

The initial bootstrap committee will consist of 5 individuals who are core stakeholders and/or contributors.

Members are (in alphabetical order):

• Emil Bäckmark, @e-backmark-ericsson, Ericsson
• Andrea Frittoli, @afrittoli, IBM
• Mattias Linnér, @m-linner-ericsson, Ericsson
• Erik Sternerson @erkist, doWhile
• Steve Taylor @sbtaylor15, DeployHub / Ortelius OS

The committee MUST:

• Represent a cross-section of interests, not just one company
• Balance technical, architectural, and governance expertise since its initial mission is the establishment of structure around contributions, community, and decision-making
• Hold staggered terms, sufficient to ensure an orderly transition of power via elections as designed and implemented by the committee (see below for specific deliverables)
• Provide designated alternates in cases where quorum is required but not attainable with the current set of members
• Communicate with the Continuous Delivery Foundation on a regular cadence

Committee Deliverables

The committee will be responsible for a series of specific artifacts and activities as outlined below.

Initial Charter

This document will define how the committee is to manage the project until it has transitioned to an elected steering body, as well as what governance must be in place. The Kubernetes Steering Committee Charter Draft serves as a good example.

A charter should cover all of the following topics:

• Scope of rights and responsibilities explicitly held by the committee
• Committee structure that meets the requirements above
• Election process, including:
  • special elections in the case someone resigns or is impeached
  • who is eligible to nominate candidates and how
  • who is eligible to run as a candidate
  • Voter registration and requirements
  • election mechanics such as
    • committee company representation quotas
    • Limits on electioneering
    • Responses to election fraud
  • How are changes to the charter enacted, and by what process
  • How are meetings conducted
    • Recorded or not, and if not, how is the information shared
    • How is work tracked? Example steering project board
    • Is there a member note taker, or is there a neutral facilitator role that exists outside of the committee?
    • Frequency, duration, and required consistency
  • Committee decision-making process, and specifically those areas of action that require more/less consensus, e.g. modifications the charter
  • Sub-Steering Committee governance structure (see this example)

Transition Process

The transition process MUST:

• Organize, execute, and validate an election for replacing bootstrap members (they may re-run, but would need to be re-elected in order to stay)
• Define the term lengths for newly-elected individuals, ideally so not all members change out at once
• Provide documentation for the community and committee members sufficient to smoothly continue the established practices of the committee

Contribution Process

The committee MUST define a contribution process that:

• Explains to potential contributors how/if they can add code to the repository/repositories
• Documents Workflow and management of pull requests
• Identifies who is authorized to commit or revert code
• Identifies automation is required for normal operations
• Defines how release decisions are made
  • Who is authorized to release and when.
  • Frequency limits
• Defines the documentation process
• Defines what Contributor License Agreement (CLA) process is required and how it is programmatically enforced before code is merged

Security/Vulnerability Reporting and Response Process

• Identify and document where vulnerability reporting can be done to the project
• Identify and document who is responsible for receiving vulnerability reports
• Document process responsible parties go through to triage and determine veracity of vulnerability
• Document process for facilitating fix, generating release update, and communicating vulnerability and fix to public

Code of Conduct

The code of conduct MUST set expectations for contributors on expected behavior, as well as explaining the consequences of violating the terms of the code. The Contributor Covenant has become the de facto standard for this language.

Members of the governance committee will be responsible for handling CDEvents code of conduct violations via cdevents-code-of-conduct@googlegroups.com.

Project Communication Channels

What are the primary communications channels the project will adopt and manage? This can include Slack, mailing lists, an organized Stack Overflow topic, or exist only in GitHub issues and pull requests.

• Mailing list: groups.google.com/g/cdevents-dev.
• Slack: #sig-events slack channel on the CDF slack.

Governance decisions, votes and questions should take place on the cdevents-governance@googlegroups.com mailing list.

Permissions and access

Members of the governing board will be given access to these resources:

• Google Groups Administrators
• GitHub Org Administrators

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 a 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 CDEvents Specification is available on our website.

The specification is currently draft and not ready for implementation. We are working towards our first release v0.1.

CDEvents SDKs

CDEvents is developing as set of SDKs:

• Go

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.