CLI for reporting events to Faros platform.
The purpose of this script is to abstract away the schema structure of the various CI/CD Faros canonical models. When attempting to send a deployment or build event to Faros, only the field values need to be specified and the script takes care of structuring and sending the request.
Please make sure the following are installed before running the script:
- curl
- jq
- uuidgen
You can download and execute the script:
$ ./faros_event.sh helpOr with curl:
# set to the latest version - https://github.com/faros-ai/faros-events-cli/releases/latest
$ export FAROS_CLI_VERSION="v0.1.0"
$ curl -s https://raw.githubusercontent.com/faros-ai/faros-events-cli/$FAROS_CLI_VERSION/faros_event.sh | bash -s helpAn event type (e.g. deployment, build) corresponds to the step of your CI/CD process that you are instrumenting. Each event type represents a set of arguments (required and optional) that are used to populate a specific set of Faros' canonical models which are then sent to Faros. The event type is the main argument passed to the cli. Below are the supported event types with their required and optional arguments.
There are two ways that arguments can be passed into the script. The first, is via flags. The second is via environment variables. You may use a combination of these two options. If both are set, flags will take precedence over environment variables.
đź“ť Note: By convention, you can switch between using a flag or an environment variable by simply capitalizing the argument name and prefixing it with FAROS_. For example, --commit_sha becomes FAROS_COMMIT_SHA, --vcs_org becomes FAROS_VCS_ORG.
| Argument | Description | Required | Default | Allowed Value |
|---|---|---|---|---|
| ‑‑api_key | Your Faros api key. See the documentation for more information on obtaining an api key. | Yes | ||
| ‑‑app | The name of the application that is being built. If this application does not already exist within Faros it will be created. You can view your applications in Faros. | Yes | ||
| ‑‑ci_source | The CI source system that contains the build. (e.g. Jenkins). Please note that this field is case sensitive. If you have a feed that connects to one of these sources, this name must match exactly to be correctly associated. |
Yes | ||
| ‑‑ci_org | The unique organization within the CI source system that contains the build. | Yes | ||
| ‑‑pipeline | The name of the pipeline that contains the build. If this pipeline does not already exist within Faros it will be created. | Yes | ||
| ‑‑url | The Faros url to send the event to. | https://prod.api.faros.ai |
||
| ‑‑graph | The graph that the event should be sent to. | "default" | ||
| ‑‑origin | The origin of the event that is being sent to faros. | "Faros_Script_Event" | ||
| ‑‑start_time | That start time of the build in milliseconds since the epoch. (e.g. 1626804346019) |
Now | ||
| ‑‑end_time | That end time of the build in milliseconds since the epoch. (e.g. 1626804346019) |
Now | ||
| ‑‑app_platform | The compute platform that runs the application. | "" |
A build event is used to communicate a specific build's status, the code being built, and where the build is taking place.
| Argument | Description | Required | Default | Allowed Value |
|---|---|---|---|---|
| ‑‑build_status | The status of the build. | Yes | Success, Failed, Canceled, Queued, Running, Unknown, Custom | |
| ‑‑vcs_source | The version control source system that stores the code that is being built. (e.g. GitHub, GitLab, Bitbucket) Please note that this field is case sensitive. If you have a feed that connects to one of these sources, this name must match exactly to be correctly associated. | Yes | ||
| ‑‑vcs_org | The unique organization within the version control source system that contains the code that is being built. (e.g. faros-ai) | Yes | ||
| ‑‑repo | The repository within the version control organization that stores the code associated to the provided commit sha. | Yes | ||
| ‑‑commit_sha | The commit sha of the code that is being built. | Yes | ||
| ‑‑build | The unique id for the build. | Yes | ||
| ‑‑build_status_details | Any additional details about the status of the build that you wish to provide. | "" |
Using flags
$ ./faros_event.sh build -k "<api_key>" \
--app "<app_name>" \
--build_status "<build_status>" \
--ci_org "<ci_organization>" \
--ci_source "<ci_source>" \
--commit_sha "<commit_sha>" \
--repo "<vcs_repo>" \
--pipeline "<ci_pipeline>" \
--vcs_source "<vcs_source>" \
--vcs_org "<vcs_organization>"Or using environment variables
$ FAROS_API_KEY="<api_key>" \
FAROS_APP="<app_name>" \
FAROS_BUILD_STATUS="<build_status>" \
FAROS_CI_ORG="<ci_org>" \
FAROS_CI_SOURCE="<ci_source>" \
FAROS_COMMIT_SHA="<commit_sha>" \
FAROS_REPO="<vcs_repo>" \
FAROS_PIPELINE="<ci_pipeline>" \
FAROS_VCS_SOURCE="<vcs_source>" \
FAROS_VCS_ORG="<vcs_org>" \
./faros_event.sh buildA deployment event communicates a deployment's status, destination environment as well as the associated build to Faros.
| Argument | Description | Required | Default | Allowed Value |
|---|---|---|---|---|
| ‑‑deployment_env | The environment that the application is being deployed to. | Yes | Prod, Staging, QA, Dev, Sandbox, Custom | |
| ‑‑deployment_status | The status of the deployment. | Yes | Success, Failed, Canceled, Queued, Running, RolledBack, Custom | |
| ‑‑build | The unique identifier of the build that constructed the artifact being deployed. | Yes | ||
| ‑‑deployment | The unique id of the deployment. | Random UUID | ||
| ‑‑deployment_env_details | Any additional details about the deployment environment that you wish to provide. | "" | ||
| ‑‑deployment_status_details | Any additional details about the status of the deployment that you wish to provide. | "" | ||
| ‑‑source | The source that will be associate with the deployment. | "Faros_Script" |
Using flags
$ ./faros_event.sh deployment -k "<api_key>" \
--app "<app_name>" \
--ci_org "<ci_organization>" \
--ci_source "<ci_source>" \
--deployment_status "<deploy_status>" \
--deployment_env "<environment>" \
--pipeline "<ci_pipeline>" \
--build "<build>"Or using environment variables
$ FAROS_API_KEY="<api_key>" \
FAROS_APP="<app_name>" \
FAROS_CI_ORG="<ci_org>" \
FAROS_CI_SOURCE="<ci_source>" \
FAROS_DEPLOYMENT_STATUS="<deploy_status>" \
FAROS_DEPLOYMENT_ENV="<environment>" \
FAROS_PIPELINE="<pipeline>" \
FAROS_BUILD="<build>" \
./faros_event.sh deploymentThe build_deployment should be used when there is not a distinct build that created the artifact that is being deployed. In order for Faros to associate the code that is being deployed, a build that links a commit sha to the deployment will be created.
| Argument | Description | Required | Default | Allowed Value |
|---|---|---|---|---|
| ‑‑deployment_env | The environment that the application is being deployed to. | Yes | Prod, Staging, QA, Dev, Sandbox, Custom | |
| ‑‑deployment_status | The status of the deployment. | Yes | Success, Failed, Canceled, Queued, Running, RolledBack, Custom | |
| ‑‑build_status | The status of the build. | Yes | Success, Failed, Canceled, Queued, Running, Unknown, Custom | |
| ‑‑vcs_source | The version control source system that stores the code that is being built/deployed. (e.g. GitHub, GitLab, Bitbucket) Please note that this field is case sensitive. If you have a feed that connects to one of these sources, this name must match exactly to be correctly associated. | Yes | ||
| ‑‑vcs_org | The unique organization within the version control source system that contains the code that is being built. (e.g. faros-ai) | Yes | ||
| ‑‑repo | The repository within the version control organization that stores the code associated to the provided commit sha. | Yes | ||
| ‑‑commit_sha | The commit sha of the code that is being built. | Yes | ||
| ‑‑deployment_start_time | The start time of the deployment in milliseconds since the epoch. (e.g.1626804346019) |
$FAROS_START_TIME | ||
| ‑‑deployment_end_time | The end time of the deployment in milliseconds since the epoch. (e.g.1626804346019) |
$FAROS_END_TIME | ||
| ‑‑build_start_time | The start time of the build in milliseconds since the epoch. (e.g.1626804346019) |
$FAROS_START_TIME | ||
| ‑‑build_end_time | The end time of the build in milliseconds since the epoch. (e.g.1626804346019) |
$FAROS_END_TIME | ||
| ‑‑deployment | The unique id of the deployment. | Random UUID | ||
| ‑‑deployment_env_details | Any additional details about the deployment environment that you wish to provide. | "" | ||
| ‑‑deployment_status_details | Any additional details about the status of the deployment that you wish to provide. | "" | ||
| ‑‑source | The source that will be associate with the deployment. | "Faros_Script" | ||
| ‑‑build | The unique identifier of the build that constructed the artifact being deployed. | Random UUID | ||
| ‑‑build_status_details | Any additional details about the status of the build that you wish to provide. | "" |
Using flags
$ ./faros_event.sh build_deployment -k "<api_key>" \
--app "<app_name>" \
--build_status "<build_status>" \
--ci_org "<ci_organization>" \
--ci_source "<ci_source>" \
--commit_sha "<commit_sha>" \
--deployment_status "<deploy_status>" \
--deployment_env "<environment>" \
--pipeline "<ci_pipeline>" \
--repo "<vcs_repo>" \
--vcs_source "<vcs_source>" \
--vcs_org "<vcs_organization>"Or using environment variables
$ FAROS_API_KEY="<api_key>" \
FAROS_APP="<app_name>" \
FAROS_BUILD_STATUS="<build_status>" \
FAROS_CI_ORG="<ci_org>" \
FAROS_CI_SOURCE="<ci_source>" \
FAROS_COMMIT_SHA="<commit_sha>" \
FAROS_DEPLOYMENT_STATUS="<deploy_status>" \
FAROS_DEPLOYMENT_ENV="<environment>" \
FAROS_REPO="<vcs_repo>" \
FAROS_PIPELINE="<pipeline>" \
FAROS_VCS_SOURCE="<vcs_source>" \
FAROS_VCS_ORG="<vcs_org>" \
./faros_event.sh build_deployment| Flag | Description |
|---|---|
| --dry_run | Print the event instead of sending. |
| --silent | Unexceptional output will be silenced. |
| --debug | Helpful information will be printed. |
We use ShellSpec to test our scripts.
brew tap shellspec/shellspec
brew install shellspecMove to the /test directory and execute shellspec
cd test && shellspec