The Faros CI/CD Instrumentation tool helps you generate code snippets that will send events to Faros with information about your builds and deployments.

Although it’s possible to construct these code blocks yourself using the Faros Event CLI docs, creating them in Faros leverages the data you have in Faros to help fill in some of the required information.

❗️

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 tool

1. Find the events generator in your Faros app under Sources > Events.
2. Complete the form
   1. Note: Data in the dropdowns is pre-populated based on the data you have in Faros. If your Faros instance doesn't yet have data representing the values you want, you can write in other values.
3. If it exists, 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!

If you are just getting started refer to our instrumentation getting started and extending events docs.

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. These values should not be hardcoded. Aside from the Faros API key, these variables are values that will be specific to each run. 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

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.

Examples

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}

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

Detailed Description of Instrumentation Tool Inputs

Each of below descriptions refers to a single input box in the instrumentation tool

1. Commit Source
   1. Source Control System
      Name of the system, e.g. “GitHub”, “BitBucket”
   2. Repository
      Name of the repository - it must exist in your Faros app in order to appear in the dropdown list.
2. Artifact Source
   1. Source System:
      The name of the application or program that is used to generate the artifact, e.g. “Docker”
   2. Organization:
      The name of your organization within the artifact system. This is a free text option that can be modified but should remain consistent between your submissions.
   3. Repository:
      Artifact Repository. Unrelated to Commit Source Repository. Within your Artifact Source System there should be something that acts like a repository.
3. Build/Run Tool
   1. Source System:
      Name of the overall system used.
   2. Organization:
      The name of your organization within the build system. This can be different from the Artifact Source Organization. Also a free text option that can be modified but should remain consistent between your submissions.
   3. Pipeline:
      The name of the pipeline as listed in your Source System. This might appear under a different name but can be thought of as a pipeline.
4. Deployment Tool
   1. Source System:
      Name of the overall system used to deploy.
   2. Application:
      The exact name of the application as listed in your source system.
   3. Environment:
      Choose from the Dropdown List or write your custom environment name under “Custom”.

Important Notions to Consider when creating the Events

It is crucial that the Artifact ID remain consistent throughout both the CI and CD events. In our system, there must be a way for CI and CD to connect, and this is through the Artifact ID. If the artifact ID isn't exactly the same in both, then the system won't recognize that the CI event is related to the CD event.

On the other hand $DEPLOY_ID and $RUN_ID are the associated IDs for the Deployment and Builds respectively, though you can format them in a way which suits your data. Ideally $COMMIT_SHA is associated with an object in your Version Control System.