Change Events

Change Events Schema

When a Change 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.

Change Event 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.

Change Event Object Schema

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.

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.

Deployment Events Collect Events via API