CI/CD Events

What is CI/CD?

CI and CD stand for Continuous Integration and Continuous Delivery (and sometimes Continuous Deployment).

Continuous Integration is the practice of regularly building, testing, and merging incremental code updates from all developers into a shared repository or artifact.

Continuous Delivery refers to the process of automatically taking artifacts from your build and deploying them to an environment. A Continuous Deployment process automatically takes artifacts and releases to the production environment without any manual stages in the middle (such as manually verifying in staging).

Together, they are used to automate the process of building, testing and deploying applications.

CI/CD in Faros

CI Data in Faros: This includes all data relevant to integrating code into a shared repository or artifact: the start time, end time and status of the integration process plus any artifacts created or commits associated.

CD Data in Faros : This includes all data relevant to deployments: the start time, end time and status of the deployment, environment information the artifact/commit being deployed and the the service/application it is being deployed to.

Integrating your CI/CD systems with Faros provides many benefits:

  • You can monitor build times across your systems and find inefficiencies in your deployment pipeline.
  • Faros can connect your CI/CD data with the rest of your data in Faros to group insights by team, by project or by application.
  • You can view metrics across your entire software development life cycle, such as lead time.

Lead Time

CI/CD data can be used in many metrics, most famously lead time. Lead time, one of the DORA metrics, tracks how long it takes commits to go from development into production.

The steps of lead time are shown above. Build steps, in orange, represent the build (sometimes called run) that results in an artifact. The start time and end time for this process are the main components of integration (CI) data.

Lead time also tracks the commit through various environments until it reaches production. For example, a commit can be deployed to dev, then staging, then production. Each of these different environments require a different deployment that should be tracked in your deployment data.

๐Ÿ“˜

Lead Time Calculation

To correctly compute lead time you will need CI information on the build (also called run) as well as separate CD data for each environment the change was deployed to.

Adding CI/CD data to Faros

Sending Events

The recommended way to get this information into Faros is to instrument your build and deployment pipelines to send events to Faros. Use the Faros Events Generator to create the code snippet to add to your pipelines.

โ—๏ธ

It's possible to collect similar data through sources but this approach requires strict naming conventions and is not recommended. If you wish to explore this please contact us at [email protected]

Using the Faros Events CLI

The Faros Events CLI is available on Github and includes code samples.

Using the Event Generator

  1. Find the events generator in your Faros app under Sources > Events.
  2. Complete the form starting with a Dev environment
  3. Copy the CI payload and paste it into your CI step
  4. Copy the CD payload and paste it into your deployment step
  5. Change the environment to whatever other environments you deploy to, copy the payload, paste and repeat!

Integrating with your build and deployment pipelines

  1. Select how you want to send the event. You can use Faros Events CLI from bash or Docker, or just go with a simple cURL.

  2. Paste the CI code into your system after an artifact build step. Paste the CD code into your system after a deployment step.

๐Ÿ“˜

Remember to set your variables

You'll notice each snippet has several variables defined. Aside from the Faros API key, these variables are values that will be specific to each run and should not be hardcoded. For example, in the CI event, the Build Started and Build End track how long the process to create the artifact took this round. It's important that if you are using both CI and CD events they use the same definition of Artifact ID

Where you put these code snippets is very system-dependent. The rule of thumb is to put the CI code snippet after the step where you build the artifact and the CD snippets after the step you deploy the artifact. We provide some examples below.

Example: Sending a CI event from Bitbucket

pipelines:
  default:
    - step:
        name: Send CI Event to Faros
        script:
          - apt-get update && apt-get install -y curl jq sed gawk
          - export FAROS_API_KEY="${FAROS_API_KEY}";
          - export CI_START_TIME="$(date +%s%N | cut -b1-13)"
          - ...
          - ...
          - export CI_END_TIME="$(date +%s%N | cut -b1-13)"
          - export CI_STATUS= < Success, Failed, Canceled >
          - ...
          - export FAROS_CLI_VERSION="v0.5.0" curl -s https://raw.githubusercontent.com/faros-ai/faros-events-cli/$FAROS_CLI_VERSION/faros_event.sh | bash -s
          - >
            ./faros_event.sh CI -k "<faros_api_key>" \
            --run "<run_source>://<run_organization>/{$RUN_PIPELINE}/{$RUN_ID}" \
            --commit "<commit_source>://<commit_organization>/{$COMMIT_REPOSITORY}/{$COMMIT_SHA}" \
            --artifact "<artifact_source>://<artifact_organization>/{$ARTIFACT_REPOSITORY}/{$ARTIFACT_ID}" \
            --run_status {$CI_STATUS} \
            --run_start_time {$CI_START_TIME} \
            --run_end_time {$CI_END_TIME}

Example: Sending CI and CD events from GitHub Actions

  1. Example using Faros Events CLI.
  2. Or use a specialized Faros CI/CD Action for GitHub from GitHub marketplace

Validating your events

The easiest way to confirm your data was added correctly to Faros is to inspect it with GraphQL.

Validating CI Events

CI events create artifacts in Faros. Run the query below to inspect your artifacts data in Faros. Check that :

  • There is at least one commit associated to the artifact that exists in the Faros system: the commit sha has a non-null sha
  • The repository exists in the Faros system: the repository name should be non-null
  • The timespan between createdAt and startedAt makes sense with regard to experienced build time of your engineers
{
  cicd {
    artifacts {
      nodes {
        uid
        commitAssociations {
          nodes {
            commit {
              id
              sha
              message
              metadata {
                isPhantom
              }
              repository {
                name
                organization {
                  name
                }
              }
            }
          }
        }
        build {
          endedAt
          startedAt
        }
      }
    }
  }
}

Validating CD Events

CD events create deployment objects. Run the query below to inspect your deployment data in Faros. Check that:

  • There are deployments in the system
  • Fields you expect to have values are not null
  • Deployment references an artifact that exists in the system: the artifact uid is non-null
  • The commit exists in the system: the commit sha is non-null
  • isPhantom is false for all
{
  cicd {
    deployments {
      nodes {
        metadata {
          origin
        }
        uid
        env {
          category
        }
        application {
          name
        }
        artifacts {
          nodes {
            artifact {
              uid
              metadata {
                isPhantom
              }
              commitAssociations {
                nodes {
                  commit {
                    metadata {
                      isPhantom
                    }
                    sha
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Validating CD and Artifacts Connection

If you are sending both CI and CD events, you will want to verify that the artifacts you create are correctly tied to their deployments. Check the following:

  • Deployment fields are non-null for the values you expect
  • The commit exists in the system: the commit sha is non-null
  • isPhantom is false for all
{
  cicd {
    artifacts {
      nodes {
        uid
        deployments {
          nodes {
            deployment {
              startedAt
              endedAt
              status {
                category
              }
              env {
                category
                detail
              }
              application {
                name
              }
            }
          }
        }
        commitAssociations {
          nodes {
            commit {
              id
              sha
              message
              metadata {
                isPhantom
              }
              repository {
                name
                organization {
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}

Visualizations

Once the CI and CD events appear in GraphQL, sync the graph so the events can be visualized in your favorite Faros dashboards and charts. If you have any questions, reach out to [email protected] for help!


Did this page help you?