This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

CDEvents Documentation

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

CDEvents specification

CDEvents logo

1 -

A CDEvents primer

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

TBD

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.

2 -

Introduction to CDEvents and specification of common metadata

Continuous Delivery Events Vocabulary

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!

This document intends to describe a set of events related to different phases of a Continuous Delivery process. These events are categorized by meaning, and the phase where they are intended to be used. These events are agnostic from any specific tool and are designed to fit a wide range of scenarios.

The phases covered by this proposal are:

  • Core Events: 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: Events emitted by changes in source code or by the creation, modification or deletion of new repositories that hold source code.
  • Continuous Integration Pipelines Events: includes events related to building, testings, packaging and releasing software artifacts, usually binaries.
  • Continuous Deployment Pipelines Events: 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.

These phases can also be considered as different profiles of the vocabulary that can be adopted independently. Also notice that we currently use the term ‘pipeline’ to denote a pipelines, workflows and related concepts. We also use the term ‘task’ to denote a job/stage/step.

Required Metadata for CD Events

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

  • Event ID: defines a unique identifier for the event
  • Event Type: defines a textual description of the event type, only event types described in this document are supported. All event types should be prefixed with cd.
  • Event Source: defines the context in which an event happened
  • Event Timestamp: defines the time when the event was produced

The following sections list the events in different phases, allowing adopters to choose the events that they are more interested in.

3 -

Continuous Delivery Core Events

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 related to activities and orchestration that needs to exist to be able to deterministically and continuously being able to delivery software to users.

A pipeline, in the context of Continuous Delivery, is the definition of a set of tasks that needs to be performed to build, test, package, release and deploy software artifacts. 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.

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.

  • PipelineRun Queued: a PipelineRun has been schedule to run
  • PipelineRun Started: a PipelineRun has started and it is running
  • PipelineRun Finished: a PipelineRun has finished it execution, the event will contain the finished status, success, error or failure

Each pipeline is defined as a set of Tasks to be performed in sequence, hence tracking this sequence might be important for some cases. A TaskRun is an instance of the Task defined inside the pipeline, as you can expect multiple execution of the pipelines (each a PipelineRun) you can also expect multiple execution of the Tasks, for that reason we use TaskRun to refer to one of these instances.

  • TaskRun Started: a TaskRun inside a PipelineRun has started.
  • TaskRun Finished: a TaskRun inside a PipelineRun has finished.

Pipeline Events MUST include the following attributes:

  • Event Type: the type is restricted to include cd.__ prefix. For example cd.pipelinerun.queued or cd.tests.started
  • PipelineRun Id: unique identifier for a pipeline execution
  • Pipeline Name: unique identifier for the pipeline, not for the instance. A pipeline can have multiple instances/runs.
  • PipelineRun Status: current status of the PipelineRun at the time when the event was emitted. If the pipeline is finished, this attribute should reflect if it finished successfully or if there was an error on the execution. Possible statuses: [Running, Finished, Error]

Optional attributes:

  • PipelineRun URL: URL to locate where pipeline instances are running
  • PipelineRun Errors: error field to indicate possible compilation, test, build and package errors.

4 -

Source Code Version Control Events

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!

This phase includes events related to changes in Source Code repositories that are relevant from a Continuous Delivery perspective.

Repository Events

These events are related to Source Code repositories

  • Repository Created Event: a new Source Code Repository was created to host source code for a project
  • Repository Modified Event: a Source Code Repository modified some of its attributes, like location, or owner
  • Repository Deleted Event: a Source Code Repository was deleted and it is not longer available
  • Branch Created Event: a Branch inside the Repository was created
  • Branch Deleted Event: a Branch inside the Repository was deleted

Repository Events MUST include the following attributes:

  • Event Type: the type is restricted to include cd.__ prefix. For example cd.repository.created or cd.repository.changeapproved
  • Repository URL: indicates the location of the source code repository for API operations, this URL needs to include the protocol used to connect to the repository. For example git:// , ssh://, https://
  • Repository Name: friendly name to list this repository to users

Optional attributes:

  • Repository Owner: indicates who is the owner of the repository, usually a user or an organization
  • Repository View URL: URL to access the repository from a user web browser

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

  • Change Created Event: 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
  • Change Reviewed Event: 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.
  • Change Merged Event: the change is merged to the target branch where it was submitted.
  • Change Abandoned Event: a tool or a user decides that the change has been inactive for a while and it can be considered abandoned.
  • Change Updated: the Change has been updated, for example a new commit is added or removed from an existing Change

Optional attributes for Change Events:

  • (TBD)

5 -

Continuous Deployment Events

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 cd.__ prefix. For example cd.service.upgraded or cd.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

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 cd.__ prefix. For example cd.build.queued or cd.artifact.packaged

Optional attributes:

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

7 -

CloudEvents Binding for CDEvents

CloudEvents Binding for CDEvents - Draft

Abstract

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

Table Of Contents

TBD

8 -

Contributor Covenant Code of Conduct

Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

Our Standards

Examples of behavior that contributes to a positive environment for our community include:

  • Demonstrating empathy and kindness toward other people
  • Being respectful of differing opinions, viewpoints, and experiences
  • Giving and gracefully accepting constructive feedback
  • Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
  • Focusing on what is best not just for us as individuals, but for the overall community

Examples of unacceptable behavior include:

  • The use of sexualized language or imagery, and sexual attention or advances of any kind
  • Trolling, insulting or derogatory comments, and personal or political attacks
  • Public or private harassment
  • Publishing others' private information, such as a physical or email address, without their explicit permission
  • Other conduct which could reasonably be considered inappropriate in a professional setting

Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at conduct@cd.foundation. All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

1. Correction

Community Impact: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

Consequence: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

2. Warning

Community Impact: A violation through a single incident or series of actions.

Consequence: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

3. Temporary Ban

Community Impact: A serious violation of community standards, including sustained inappropriate behavior.

Consequence: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

4. Permanent Ban

Community Impact: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

Consequence: A permanent ban from any sort of public interaction within the community.

Attribution

This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

Community Impact Guidelines were inspired by Mozilla’s code of conduct enforcement ladder.

For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

9 -

CDEvents Bootstrap Governance

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

Members are (in alphabetical order):

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.

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

10 -

CDEvents

We are working on a draft version of our specification that is not yet ready for implementation. For more information check out our spec