GitLab CI

Integrate GitLab CI with CTO.ai

The CTO.ai GitLab CI/CD Template lets you integrate your existing development workflows from GitLab CI with the CTO.ai platform. However, you choose to make GitLab CI part of your development process, our template gives you granular control of the events collected by the CTO.ai platform and allows you to send Insights Events at the points in your existing workflows where it makes the most sense.

Before you begin, you may want to review our documentation on Insights Events to better understand the concepts implemented by our platform.

GitLab CI/CD Template

This integration is available as a public repository on GitHub.

To make use of this template, you can drop the following job snippet into the definition of your GitLab CI/CD Pipeline, after the job in the pipeline responsible for the deployment of your application:

include:
  - remote: 'https://raw.githubusercontent.com/cto-ai/events-gitlab-template/v0.0.2/cto.gitlab-ci.yml'

deploy_success:
  stage: cto_event
  variables:
    TEAM_ID: "${CTOAI_TEAM_ID}"
    TOKEN: "${CTOAI_EVENTS_API_TOKEN}"
    EVENT_NAME: "deployment"
    EVENT_ACTION: "success"
  when: on_success # Trigger if all jobs in pipeline were successful
  environment:
    name: production
  extends:
    - .cto-notify-event

deploy_failure:
  stage: cto_event
  variables:
    TEAM_ID: "${CTOAI_TEAM_ID}"
    TOKEN: "${CTOAI_EVENTS_API_TOKEN}"
    EVENT_NAME: "deployment"
    EVENT_ACTION: "failure"
  # Trigger if any of jobs in pipeline failed.
  # Jobs with `allow_failure` will not be considered failed regardless.
  when: on_failure
  environment:
    name: production
  extends:
    - .cto-notify-event

stages:
  # Previous Jobs
  - cto_event

You can use rules to control when your success and failure events are triggered.

We recommend adding the environment value for each job to help differentiate multiple deployment events from the same repository to different environments or workflows. This value will be reflected on your Insights Dashboard.

The above snippet expects that you have set environment variables for CTOAI_EVENTS_API_TOKEN and CTOAI_TEAM_ID in your GitLab CI/CD settings. Be sure to mask and protect the variables you set.

Instructions for finding these values can be found on our Collect Events via API page.

Deployment Events

For more information on the expected fields for Deployment Events, please see the Event Schema Reference page.

$TOKEN

required

Your API token for the CTO.ai platform.

$TEAM_ID

required

The ID of the Team on the CTO.ai platform to associate with this event. This environment variable corresponds to the team_id field in the deployment event schema.

$EVENT_NAME

required

For deployment events, this value must always be deployment. This environment variable corresponds to the event_name field in the deployment event schema.

$EVENT_ACTION

required

This should be one of the Deployment Lifecycle States defined on the Event Types page. This environment variable corresponds to the event_action field in the deployment event schema.

$BRANCH

The name of the branch that triggered the deployment. This environment variable corresponds to the branch field in the deployment event schema.

This environment variable is optional and defaults to the value of $CI_COMMIT_BRANCH if not specified.

$COMMIT

The SHA hash of the commit that triggered the deployment. This environment variable corresponds to the commit field in the deployment event schema.

This environment variable is optional and defaults to the value of $CI_COMMIT_SHA if not specified.

$REPO

The name of the repository that triggered the deployment. This environment variable corresponds to the repo field in the deployment event schema.

This environment variable is optional and defaults to the value of $CI_PROJECT_PATH if not specified.

$ENVIRONMENT

A string that uniquely represents the environment that the deployment is targeting. This environment variable corresponds to the environment field in the deployment event schema.

This environment variable is optional and defaults to the value of $CI_ENVIRONMENT_NAME if not specified.

$IMAGE

Optionally provide an identifier for the container image that is associated with the current deployment. This environment variable corresponds to the image field in the deployment event schema.

CircleCI Orb