Event Schema Reference

Reference for Lifecycle Event Schema

The types of Events supported by the CTO.ai platform are divided among a pair of categories: Deployment Events and Change Events. The purpose of this page is to document the different types of Events currently recognized by the CTO.ai platform.

When an Event is sent to our platform from an integration, it is transformed into a standardized format in line with the schemas documented on this page. In all cases, the raw Event data—from both known and unknown Event types—is also stored in our database for possible use in the future.

Event State Definitions

This section describes the different workflow states that are currently represented within the CTO.ai platform. Irrespective of source, all supported Events received from our integrations are transformed into one of these states before being processed by our platform or used to calculate Insights metrics.

Deployment Lifecycle States

Deployment Events represent the different states of your infrastructure as a deployment occurs.

For deriving Insights about your deployment processes, we currently use just two events—Success and Failure—which record the completion status of a deployment process. However, we still collect other events for use in workflow triggers and other future uses.

Name	Event Description
Success	Deployment of new change has completed successfully.
Failure	Deployment of new change has failed.
Started	Deployment of new change has started.
Progressing	Deployment of new change is in progress.
Blocked	Deployment of new change is blocked. The cause of the blocked deployment is dependent on the source infrastructure. (For example, the deployment mechanism may have features that allow deployments to wait for approval.)

Change Lifecycle States

Change Events represent different stages of the development (change) lifecycle.

Two events matter for deriving Insights about your development processes: Open and Merge. However, we still collect other events for use in workflow triggers and other future uses.

Name	Event Description
Open	New Pull Request has been created at the source.
Review Requested	Review has been requested on the Pull Request.
Change Requested	Changes have been requested by the reviewer of the Pull Request.
Change	Changes have been made by the author in response to the requested review of the Pull Request.
Merge	Pull Request and the changes it contains have been merged into base branch.
Close	Pull Request has been closed without merging commits into base branch.
Reopen	Pull Request that was closed has been opened for review.

Event Object Schemas

Beyond receiving Events from our integrations, you can also send Events to our platform via our API. This section documents the schemas for the expected format of Events sent to our platform.

For more information about integrating your development lifecycle with the CTO.ai platform directly through our API, head over to our Collect Events via API page.

Deployment Event Schema

Deployment Events represent the different stages of your infrastructure as a deployment occurs. This is the general structure of a JSON object representing a Deployment Event:

{
   "branch": "",
   "commit": "",
   "environment": "",
   "event_action": "{started|progressing|blocked|success|failure}",
   "event_name": "deployment",
   "finished_at": "",
   "id": 12345,
   "image": "",
   "meta": "",
   "repo": "",
   "started_at": "",
   "team_id": "",
   "vcs": "[name of vcs provider]"
}

event_name

stringrequired

For deployment events, this value must always be deployment.

event_action

stringrequired

This should be one of the Deployment Lifecycle States defined on the Event Types page.

Accepted Values

The value of this field should be one of the following:

started
progressing
blocked
success
failure

vcs

stringrequired

The name of the Verson Control System (VCS) provider that originated the deployment.

repo

stringrequired

The name of the repository that triggered the deployment.

branch

stringrequired

The name of the branch that triggered the deployment.

commit

stringrequired

The SHA hash of the commit that triggered the deployment.

environment

stringrequired

A string that uniquely represents the environment that the deployment is targeting.

team_id

stringrequired

The ID of the Team on the CTO.ai platform to associate with this event.

id

integer

Optionally provide an ID for this deployment event.

started_at

string

A datetime string in ISO 8601 format that indicates when the Deployment Lifecycle entered the current state.

finished_at

string

A datetime string in ISO 8601 format that indicates when the Deployment Lifecycle exited the current state.

image

string

Optionally provide an identifier for the container image that is associated with the current deployment.

meta

object

Optionally provide a JSON object that contains additional metadata about the event.

origin_type: string; Optionally provide a string that indicates the type of origin that triggered the deployment.
user: string; Optionally provide the identifier (from the VCS provider) of the user that triggered the deployment.

Change Event Schema

Change Events represent different stages of the development (change) lifecycle. This is the general structure of a JSON object representing a Change Event:

{
   "author": "",
   "base": "",
   "created_at": "",
   "event_action": "{open|review_request|change_requested|change|merge|close|reopen}",
   "event_name": "change",
   "labels": [],
   "meta": "",
   "number": 12345,
   "target": "",
   "team_id": "",
   "title": ""
}

event_name

stringrequired

For change events, this value must always be change.

event_action

stringrequired

This should be one of the Change Lifecycle States defined on the Event Types page.

Accepted Values

The value of this field should be one of the following:

open
review_request
change_requested
change
merge
close
reopen

number

integerrequired

A unique identifier for the current Change Lifecycle.

If this event represents activity on a Pull Request, for example, then this value would be the Pull Request number at the VCS provider.

author

stringrequired

The username on the CTO.ai platform for the user that triggered the current change.

team_id

stringrequired

The ID of the Team on the CTO.ai platform to associate with this event.

title

stringrequired

Describe the nature of the change that is represented by this Change Lifecycle Event.

If this event represents activity on a Pull Request, for example, then this value would be the title of the Pull Request at the VCS provider.

base

objectrequired

Provide an object that describes the base repository represented by the current Change Lifecycle event.

Generally speaking, the base repo metadata will represent the fork or branch that contains your current production code (e.g. main or master on the common instance of your repo hosted by your VCS provider).

branch: stringrequired; Provide the name of the relevant branch of the base repo that is represented by the current Change Lifecycle event.
commit: stringrequired; Provide the SHA hash of the head commit of the relevant branch of the base repo that is represented by the current Change Lifecycle event.
repo: stringrequired; Provide the full name of the base repository that is represented by the current Change Lifecycle event.

target

objectrequired

Provide an object that describes the target repository represented by the current Change Lifecycle event.

Generally speaking, the target repo metadata will represent the fork or branch that contains your current work-in-progress code (e.g. feature-branch on the common instance of your repo hosted by your VCS provider or on your own fork of the repository).

branch: stringrequired; Provide the name of the relevant branch of the target repo that is represented by the current Change Lifecycle event.
commit: stringrequired; Provide the SHA hash of the head commit of the relevant branch of the target repo that is represented by the current Change Lifecycle event.
repo: stringrequired; Provide the full name of the target repository that is represented by the current Change Lifecycle event.

labels

array of strings

An optional array of any label strings that are associated with the current Change Lifecycle.

created_at

string

Optionally provide a datetime string in ISO 8601 format that indicates when the current Change Lifecycle event was created.

meta

object

Optionally provide a JSON object that contains additional metadata about the event.

origin_type: string; Optionally provide a string that indicates the type of origin that triggered the deployment.
user: string; Optionally provide the identifier (from the VCS provider) of the user that triggered the deployment.

Lifecycle Integration Collect Events via API