DOCSEARCHbyAlgolia
Submit Docs

CDEvents Specification

repository·main·Indexed 41 days ago

https://github.com/cdevents/spec

A standardized event specification for Continuous Delivery designed to enable interoperability between CI/CD tools, platforms, and observability systems. It provides a common vocabulary for core, source code control, CI, CD, operations, and testing events, extending the CloudEvents specification with specific CD semantics.

Tokens
20.2K
Snippets
42
Records
78
Agent score
49%

What's inside CDEvents

  1. Overview of the CDEvents Specification

    main

    CDEvents is a common specification for Continuous Delivery (CD) events designed to enable interoperability across the software production ecosystem. It provides a standardized vocabulary of events that allows different CI/CD tools and platforms to communicate seamlessly.

    By extending efforts like CloudEvents with specific purpose and semantics, CDEvents enables better observability and provides consistent measuring points for metrics across complex pipelines. The specification is an incubated project at the Continuous Delivery Foundation (CDF).

  2. Continuous Integration (CI) Subjects: build and artifact

    main

    The Continuous Integration specification defines two primary subjects that represent the core entities in a CI pipeline:

    1. build: A process that uses a recipe to produce an artifact from source code. It is typically orchestrated by a CI system or a specific build tool.
    2. artifact: An output of a build process. Events related to artifacts (like packaging, signing, or publishing) can be generated by the build system or the artifact storage/registry system.

    Note: testCase and testSuite events are handled in the separate Testing Events specification.

  3. Understand Custom Event Types in CDEvents

    main

    Custom event types are used for events that are strictly tool-specific and not suitable for the general CDEvents interoperability specification. They serve as an interim solution for tools to adopt the CDEvents format before their specific events are officially standardized.

    Key constraints for custom events:

    • Use the dev.cdeventsx event-type namespace.
    • Subjects must follow the format <tool-name>-<subject-name> to prevent conflicts.
    • Events must always validate against the official CDEvents schema.
    • Events may provide an additional schema via the schemaUri property in the context object.
    • Any event using the dev.cdeventsx.* type must also respect the dev.cdeventsx JSONSchema.

  4. Understand CDEvents linking and chains

    main

    CDEvents uses Chains and Links to provide context for activity sequences in the CI/CD lifecycle.

    • A Chain is an end-to-end representation of all activities performed for a specific entity. It is identified by a chainId (a UUID) which acts as a bucket for all related events.
    • A Link is an object describing how one event relates to another.

    This mechanism allows systems to move beyond simple attribute backtracking (like using a shared id) and instead provides a clear way to define when an activity chain starts and finishes, enabling complex patterns like Fan Out/Fan In (parallel tasks merging back into a single process) and supporting Generic UIs that can visualize the entire lifecycle of a request across different tools.

  5. Understand Continuous Operations subjects: incident and ticket

    main

    Continuous Operations events track the operational health and management of deployed services. This specification defines two primary subjects:

    1. incident: Represents a problem in a production environment that jeopardizes confidentiality, integrity, or availability.
    2. ticket: Represents a record in a ticketing system used to request changes, report problems, or document incidents.

    These subjects can be managed by various actors including SREs, monitoring systems, quality gates, or the services themselves.

  6. Understand the CDEvent subject structure

    main

    The subject describes the entity that the event is about.

    Required Subject Attributes

    • id: A non-empty String identifier for the subject. Subsequent events related to the same subject MUST use this same id.
    • content: An Object containing the relevant details of the subject. The specific shape of this object depends on the event type defined in the context.

    Optional Subject Attributes

    • source: A URI-Reference defining the context in which the subject originated. This should only be used if the subject's source differs from the event's source in the context.
    {
   "context": {
      "specversion": "0.6.0-draft",
      "id" : "A234-1234-1234",
      "source" : "/staging/tekton/",
      "type" : "dev.cdevents.taskrun.started.0.2.0",
      "timestamp" : "2018-04-05T17:31:00Z"
   },
   "subject" : {
      "id": "my-taskrun-123",
      "content": {
         "task": "my-task",
         "uri": "/apis/tekton.dev/v1beta1/namespaces/default/taskruns/my-taskrun-123",
         "pipelineRun": {
            "id": "my-distributed-pipelinerun",
            "source": "/tenant1/tekton/"
         }
      }
   }
}

  7. Understand the CDEvents Vocabulary structure

    main

    The CDEvents vocabulary is built using three primary components to define an event type:

    1. Subjects: The core entities or objects involved in an event (e.g., a build). Subjects are of type Object and have associated attributes defined by the event type schema (some mandatory, some optional).
    2. Predicates: The actions or states applied to a subject (e.g., a build being started or finished).
    3. Attributes: Metadata associated with the subject.

    An event type is essentially the combination of a subject and its predicates. Subjects can serve as the core context of an event or be referenced elsewhere in the protocol.

  8. Understand Testing Events subjects and lifecycle

    main

    Testing events track test execution performed independently or within CI/CD pipelines. The specification defines three primary subjects: testCaseRun, testSuiteRun, and testOutput.

    Lifecycle of a testCaseRun

    To ensure conformance, testCaseRun events must follow these state transition rules:

    • Initial Events: queued, started, or skipped.
    • Terminal Events: finished and skipped (no further events should follow these).
    • Transitions:
      • A queued event must be followed by either started or finished.
      • A started event must be followed by a finished event.

    Subject Summary

    SubjectDescriptionPredicates
    testCaseRunThe execution of a software testCasequeued, started, finished, skipped
    testSuiteRunThe execution of a software testSuitequeued, started, finished
    testOutputAn output artifact produced by a testCaseRunpublished

  9. Understand the CDEvent context structure

    main

    A CDEvent is composed of a context and a subject. The context contains metadata about the event itself, such as its unique identifier, type, source, and timestamp.

    Required Context Attributes

    • id: A unique non-empty String identifier for the event within the given source. A UUID v4 is a common example.
    • type: A String defining the event type using the pattern dev.cdevents.<subject>.<predicate>.<major>.<minor>.<patch>.
      • Standard CDEvents use the dev.cdevents. prefix.
      • Custom events (defined outside the core spec) use the dev.cdeventsx. prefix.
    • source: A URI-Reference defining the context where the event occurred (e.g., /tekton or https://www.jenkins.io/). It provides global uniqueness when combined with id.
    • timestamp: A timestamp adhering to [RFC 3339] representing when the event occurred.
    • specversion: A String indicating the CDEvents specification version (e.g., 0.1.1).

    Optional Context Attributes

    • schemaUri: An absolute URI linking to a jsonschema that refines the event schema. This schema must be stricter than the base CDEvents schema.
    • chainId: A String (UUID v4) identifying a chain of events.
    • links: A List of link objects used to indicate connections between events (e.g., PATH, RELATION, or END).
    {
    "context": {
    "specversion": "0.6.0-draft",
    "id" : "A234-1234-1234",
    "source" : "/staging/tekton/",
    "type" : "dev.cdevents.taskrun.started.0.2.0",
    "timestamp" : "2018-04-05T17:31:00Z",
    "schemaUri":  "https://myorg.com/cdevents/schema/taskrun-started-1-1-0"
  }
}

  10. Format CloudEvents Data for CDEvents

    main

    The CloudEvents Event Data MUST contain the complete CDEvents object, including the context, subject, and any customData, rendered as JSON according to the schema for that specific event type.

    Handling Custom Data:

    • If customData is of type application/json, it MUST be embedded as-is.
    • For any other content-type, the data MUST be base64 encoded and set as the value for the customData field.

    HTTP Binding Requirements:

    • In HTTP binary mode: The CloudEvents context is stored in HTTP headers, and the Content-Type header MUST be set to application/json.
    • In HTTP structured mode: The datacontenttype field in the CloudEvents context carries the content type information.

  11. Understand Continuous Deployment (CD) subjects: environment and service

    main

    In the Continuous Deployment specification, two primary subjects are used to model the state of software delivery:

    1. environment: A platform capable of running services (e.g., a Kubernetes cluster, a cloud zone, or a CI runner). It tracks lifecycle changes like creation, modification, and deletion.
    2. service: A running artifact within an environment. This can represent a binary, a daemon, an application, or a Docker container. It tracks lifecycle changes like deployment, upgrades, rollbacks, removal, and publication.

    An environment acts as the container for a service.

  12. Understand Source Code Control subjects

    main

    Source Code Control events in CDEvents revolve around three primary subjects that track changes in SCM repositories relevant to Continuous Delivery:

    • repository: A software configuration management (SCM) repository. It can emit events related to proposed source code changes.
    • branch: A specific branch within an SCM repository.
    • change: A proposed set of changes to a repository's content (e.g., a Pull Request or Merge Request). A change can include one or multiple commits.

    These subjects are triggered by actions from developers or automated bots.