# CDEvents Integration

CDEvents (Continuous Delivery Events) is a **standardized event format** for event-driven communication in CI/CD and DevOps systems. Designed to work with platforms like Tekton, Jenkins, ArgoCD, Flux, and other modern DevOps frameworks.

For further details on CDEvents, refer to the official [CDEvents Specification](https://cdevents.dev/).

## Importing CDEvents Build Data

{% hint style="info" %}
Before using this API, ensure that your CI/CD tooling is configured to emit **CDEvents**.
{% endhint %}

To ensure the accuracy of data in Logilica, CDEvents data should adhere to the following guide:

1. Import a repository to Logilica and fetch the `ID` through the API or UI. You use this `ID` in subsequent calls to the Logilica Import API for CDEvents Data.
2. Send CDEvents to the API. The API expects events in chronological order.

In Logilica, a CI build data entry is constructed across the ingestion of multiple CDEvents events. The creation of the complete CI build entry is triggered when an event with a type of `dev.cdevents.pipelinerun.finished` is received. Partial CI build entry records are not shown in the Logilica UI. The `context.id` field is used across the multiple CDEvent events to create one CI build entry in Logilica.

### Mapping of CDEvents to Logilica CI Build <a href="#upload-example-using-curl" id="upload-example-using-curl"></a>

The following table outlines how CDEvents are mapped to the attributes of [CI builds in Logilica](https://docs.logilica.com/advanced/import/build-data/..#ci_build-repoid-create). Each event contributes specific data that is aggregated to form a complete build record

<table><thead><tr><th width="217">Logilica CI Build</th><th width="269">CDEvent Type</th><th>CDEvent Field</th></tr></thead><tbody><tr><td>name</td><td>pipelinerun</td><td>pipelineName</td></tr><tr><td>url</td><td>pipelinerun</td><td>outcome</td></tr><tr><td>startedAt</td><td>pipelinerun</td><td>timestamp and type includes 'running'</td></tr><tr><td>createdAt</td><td>pipelinerun</td><td>timestamp and type includes 'queued'</td></tr><tr><td>completedAt</td><td>pipelinerun</td><td>timestamp and type includes 'completed'</td></tr><tr><td>stages</td><td>build</td><td>id, timestamp</td></tr><tr><td>repoUrl</td><td>repository</td><td>url</td></tr><tr><td>commit</td><td>change</td><td>id</td></tr><tr><td>triggeredBy</td><td>customData</td><td></td></tr><tr><td>pullRequestUrls</td><td>customData</td><td></td></tr></tbody></table>

In addition, Logilica's CDEvents integration supports the additional fields of `triggeredBy` and `pullRequestUrls` through the use of custom data field, specified in a **JSON string format** (refer to cURL example below).

{% hint style="info" %}
**Using custom data** requires the CDEvents to have `customDataContentType: "application/json"`
{% endhint %}

### Upload Example Using cURL <a href="#upload-example-using-curl" id="upload-example-using-curl"></a>

In the following, we provide an example of how to push your CDEvents data into Logilica for storage and built-in analytics.

{% hint style="info" %}
**Important**: Ensure the repository you build from is already **onboarded** in Logilica.\
The [Repositories API](https://docs.logilica.com/advanced/import/repositories) can be used to retrieve the `repoId` for the endpoint.
{% endhint %}

The cURL POST command has been provided below. Note, that the POST command uses example data, including the API token `lgca_UeRxFs_3RYRJEJtdYp7j7Wa6DirG5NjiYslsb` and the example workspace `myworkspace`. The command URL also includes a placeholder for the repoID to associate the uploaded CD Events with.

```
curl -L \
  --request POST \
  --url 'https://logilica.io/api/import/v1/cd_events/<repoID>/create' \
  --header 'X-lgca-token: lgca_UeRxFs_3RYRJEJtdYp7j7Wa6DirG5NjiYslsb' \
  --header 'x-lgca-domain: myworkspace' \
  --header 'Content-Type: application/json' \
  --data '{  
    "context": {
        "version": "0.1.2",
        "id": "event-123",
        "source": "/event/source/123",
        "type": "dev.cdevents.pipelinerun.finished",
        "timestamp": "2025-03-05T10:00:00Z"
    },
    "subject": {
        "id": "pipeline-123",
        "source": "/event/source/123",
        "type": "pipelineRun",
        "content": {
            "id": "pipeline-123",
            "source": "/event/source/123"",
            "type": "dev.cdevents.build.finished",
            "pipelineName": "example-pipeline",
            "url": "https://ci.example.com/pipeline/67890",
            "outcome": "success"
        }
    },
    "customData": "{\"triggeredBy\": \"John Doe\", \"pullRequestUrls\": [\"https://github.com/org/pull/123"]}",
    "customDataContentType": "application/json"
}'
```

## API Schema for Importing CDEvents

### Create a CDEvent

{% openapi src="<https://3637178088-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvMP8keAdyp2axoLILtL5%2Fuploads%2Fgit-blob-d8a87b720df94b60e4756c4b7d2c1bfce151c6a1%2Fopenapi.json?alt=media>" path="cd\_events/{repoID}/create" method="post" %}
[openapi.json](https://3637178088-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvMP8keAdyp2axoLILtL5%2Fuploads%2Fgit-blob-d8a87b720df94b60e4756c4b7d2c1bfce151c6a1%2Fopenapi.json?alt=media)
{% endopenapi %}