Skip to main content

CircleCI

This Integration is part of the CircleCI Pack.#

Supported versions

Supported Cortex XSOAR versions: 5.5.0 and later.

Gets the details of the CircleCI workflows; including the details of the last runs and the jobs, and retrieves the artifacts of the jobs. This integration was integrated and tested with version v2 of CircleCI.

Configure CircleCI on Cortex XSOAR#

  1. Navigate to Settings > Integrations > Servers & Services.

  2. Search for CircleCI.

  3. Click Add Instance to create and configure a new integration instance.

    ParameterDescriptionRequired
    Your server URLTrue
    API keyThe API key used to connectTrue
    Version control system typeType of version control systemTrue
    Organization NameName of the organizationTrue
    Project NameName of the projectTrue
    Trust any certificate (not secure)True
    Use system proxy settingsFalse
  4. Click Test to validate the URLs, token, and connection.

Commands#

You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook. After you successfully execute a command, a DBot message appears in the War Room with the command details.

circleci-workflows-list#


Gets information on workflows.

Base Command#

circleci-workflows-list

Input#

Argument NameDescriptionRequired
limitMaximum number of workflows to retrieve. Default is 20.Optional
vcs_typeVersion control system type of the project. Possible values: "github" and bitbucket". Default is github.Optional
organizationOrganization from which to retrieve workflows. Defaults to the organization instance parameter.Optional
projectProject from which to retrieve workflows. Defaults to the project instance parameter.Optional

Context Output#

PathTypeDescription
CircleCI.Workflow.metrics.duration_metrics.maxNumberMaximum workflow run time.
CircleCI.Workflow.metrics.duration_metrics.meanNumberMean workflow run time.
CircleCI.Workflow.metrics.duration_metrics.medianNumberMedian workflow run time.
CircleCI.Workflow.metrics.duration_metrics.minNumberMinimum workflow run time.
CircleCI.Workflow.metrics.duration_metrics.p95Number95th percentile workflow run time.
CircleCI.Workflow.metrics.duration_metrics.standard_deviationNumberThe standard deviation of the workflow run time.
CircleCI.Workflow.metrics.duration_metrics.total_durationNumberTotal duration.
CircleCI.Workflow.metrics.failed_runsNumberNumber of failed workflow runs.
CircleCI.Workflow.metrics.median_credits_usedNumberMedian credits used.
CircleCI.Workflow.metrics.mttrNumberMean recovery time.
CircleCI.Workflow.metrics.success_rateNumberSuccess rate.
CircleCI.Workflow.metrics.successful_runsNumberNumber of successful runs.
CircleCI.Workflow.metrics.throughputNumberThroughput.
CircleCI.Workflow.metrics.total_credits_usedNumberTotal credits used.
CircleCI.Workflow.metrics.total_recoveriesNumberTotal recoveries.
CircleCI.Workflow.metrics.total_runsNumberTotal runs.
CircleCI.Workflow.nameStringWorkflow name.
CircleCI.Workflow.project_idStringThe project ID that the workflow belongs to.
CircleCI.Workflow.window_endDateWhen the workflow ended.
CircleCI.Workflow.window_startDateWhen the workflow started.

Command Example#

!circleci-workflows-list limit=2

Context Example#

{
"CircleCI": {
"Workflow": {
"metrics": {
"duration_metrics": {
"max": 6011,
"mean": 4508,
"median": 4508,
"min": 3005,
"p95": 5860,
"standard_deviation": 2125,
"total_duration": 0
},
"failed_runs": 1,
"median_credits_used": 0,
"mttr": 0,
"success_rate": 0.5,
"successful_runs": 1,
"throughput": 0.2,
"total_credits_used": 1900,
"total_recoveries": 0,
"total_runs": 2
},
"name": "bucket_upload_trigger",
"project_id": "4eaba5af-8c43-43ec-b469-3968d8a76f68",
"window_end": "2021-04-22T14:28:57.252Z",
"window_start": "2021-04-13T12:31:14.409Z"
}
}
}

Human Readable Output#

CircleCI Workflows#

MetricsNameProjectIdWindowEndWindowStart
total_runs: 181
successful_runs: 136
mttr: 93519
total_credits_used: 323000
failed_runs: 43
median_credits_used: 0
success_rate: 0.7513812154696132
duration_metrics: {"min": 202, "mean": 8807, "median": 8606, "p95": 11307, "max": 16317, "standard_deviation": 1707.0, "total_duration": 0}
total_recoveries: 0
throughput: 2.033707865168539
bucket_upload4eaba5af-8c43-43ec-b469-3968d8a76f682021-06-28T23:42:38.647Z2021-03-31T09:01:11.412Z
total_runs: 2
successful_runs: 1
mttr: 0
total_credits_used: 1900
failed_runs: 1
median_credits_used: 0
success_rate: 0.5
duration_metrics: {"min": 3005, "mean": 4508, "median": 4508, "p95": 5860, "max": 6011, "standard_deviation": 2125.0, "total_duration": 0}
total_recoveries: 0
throughput: 0.2
bucket_upload_trigger4eaba5af-8c43-43ec-b469-3968d8a76f682021-04-22T14:28:57.252Z2021-04-13T12:31:14.409Z

circleci-artifacts-list#


Retrieves the artifacts list from the CircleCI job.

Base Command#

circleci-artifacts-list

Input#

Argument NameDescriptionRequired
job_numberThe number of the job from which to retrieve its artifacts, e.g., 31263.Required
artifact_suffixReturns only the artifacts for which the suffix corresponds to the given suffix, e.g., 'test_failures.txt' will only retrieve the artifacts for which the suffix ends with test_failures.txt.Optional
limitMaximum number of artifacts to retrieve. Default is 20.Optional
vcs_typeThe version control system type of the project. Possible values: "github" and "bitbucket". Default is github.Optional
organizationOrganization from which to retrieve artifacts. Defaults to the organization instance parameter.Optional
projectProject from which to retrieve artifacts. Defaults to the project instance parameter.Optional

Context Output#

PathTypeDescription
CircleCI.Artifact.pathStringArtifact relative path.
CircleCI.Artifact.node_indexNumberArtifact node index.
CircleCI.Artifact.urlStringArtifact URL.

Command Example#

!circleci-artifacts-list job_number=390115 limit=2

Context Example#

{
"CircleCI": {
"Artifact": [
{
"node_index": 0,
"path": "artifacts/env.json",
"url": "https://390115-12353212-gh.circle-artifacts.com/0/artifacts/env.json"
},
{
"node_index": 0,
"path": "artifacts/debug_log.log",
"url": "https://390115-12353212-gh.circle-artifacts.com/0/artifacts/debug_log.log"
}
]
}
}

Human Readable Output#

CircleCI Artifacts#

NodeIndexPathUrl
0artifacts/env.jsonhttps://390115-12353212-gh.circle-artifacts.com/0/artifacts/env.json
0artifacts/debug_log.loghttps://390115-12353212-gh.circle-artifacts.com/0/artifacts/debug_log.log

circleci-workflow-jobs-list#


Retrieves the jobs list from the CircleCI workflow.

Base Command#

circleci-workflow-jobs-list

Input#

Argument NameDescriptionRequired
workflow_idThe workflow ID from which to retrieve its jobs, e.g., 12zxcase-12za-as51-123zs4sdgf12.Required
limitThe maximum number of jobs to retrieve. Default is 20.Optional

Context Output#

PathTypeDescription
CircleCI.WorkflowJob.idStringJob ID.
CircleCI.WorkflowJob.job_numberNumberJob number.
CircleCI.WorkflowJob.nameStringJob name.
CircleCI.WorkflowJob.project_slugStringJob project slug.
CircleCI.WorkflowJob.started_atDateTime the job started.
CircleCI.WorkflowJob.statusStringJob status.
CircleCI.WorkflowJob.stopped_atDateTime the job stopped.
CircleCI.WorkflowJob.typeStringJob type.
CircleCI.WorkflowJob.dependenciesStringJob dependencies.

Command Example#

!circleci-workflow-jobs-list workflow_id=f85efae0-cbf4-4b6d-b136-e3db67d41221 limit=2

Context Example#

{
"CircleCI": {
"Workflow": {
"Job": [
{
"dependencies": [],
"id": "c7425325-bb57-4e78-968f-2c9867d31z11",
"job_number": 389133,
"name": "Setup Environment",
"project_slug": "gh/organization_name/repo_name",
"started_at": "2021-06-24T00:04:57Z",
"status": "success",
"stopped_at": "2021-06-24T00:06:32Z",
"type": "build"
},
{
"dependencies": [
"c7425325-bb57-4e78-968f-2c9867d31z11"
],
"id": "89d36e04-5481-48a3-8be4-ddcb2bdcz1q1",
"job_number": 389166,
"name": "Run Validations",
"project_slug": "gh/organization_name/repo_name",
"started_at": "2021-06-24T00:06:35Z",
"status": "success",
"stopped_at": "2021-06-24T00:38:00Z",
"type": "build"
}
]
}
}
}

Human Readable Output#

CircleCI Workflow f85efae0-cbf4-4b6d-b136-e3db67d41221 Jobs#

DependenciesIdJobNumberNameProjectSlugStartedAtStatusStoppedAtType
c7425325-bb57-4e78-968f-2c9867d31z11389133Setup Environmentgh/organization_name/repo_name2021-06-24T00:04:57Zsuccess2021-06-24T00:06:32Zbuild
c7425325-bb57-4e78-968f-2c9867d31z1189d36e04-5481-48a3-8be4-ddcb2bdcz1q1389166Run Validationsgh/organization_name/repo_name2021-06-24T00:06:35Zsuccess2021-06-24T00:38:00Zbuild

circleci-workflow-last-runs#


Retrieves the jobs list from the CircleCI workflow.

Base Command#

circleci-workflow-last-runs

Input#

Argument NameDescriptionRequired
workflow_nameName of the workflow from which to retrieve its last runs details.Required
limitMaximum number of workflow runs to retrieve. Default is 20.Optional
vcs_typeVersion control system type of the project. Possible values: "github" and "bitbucket". Default is github.Optional
organizationOrganization from which to retrieve workflow last runs. Defaults to the organization instance parameter.Optional
projectProject from which to retrieve workflow last runs. Defaults to the project instance parameter.Optional

Context Output#

PathTypeDescription
CircleCI.WorkflowRun.branchStringBranch name.
CircleCI.WorkflowRun.created_atDateTime run created.
CircleCI.WorkflowRun.credits_usedNumberCredits used.
CircleCI.WorkflowRun.durationNumberDuration of run in seconds.
CircleCI.WorkflowRun.idStringID of the run.
CircleCI.WorkflowRun.statusStringRun status.
CircleCI.WorkflowRun.stopped_atDateTime run stopped.

Command Example#

!circleci-workflow-last-runs workflow_name=nightly limit=2

Context Example#

{
"CircleCI": {
"WorkflowRun": [
{
"branch": "master",
"created_at": "2021-06-29T00:04:56.069Z",
"credits_used": 2482,
"duration": 7743,
"id": "d832d004-0069-4412-8e6d-41265143411z",
"status": "failed",
"stopped_at": "2021-06-29T02:13:59.354Z"
},
{
"branch": "master",
"created_at": "2021-06-28T00:04:55.409Z",
"credits_used": 3129,
"duration": 9778,
"id": "531e678e-73e3-4f2a-ac80-55aa203461za",
"status": "failed",
"stopped_at": "2021-06-28T02:47:52.916Z"
}
]
}
}

Human Readable Output#

CircleCI Workflow nightly Last Runs#

BranchCreatedAtCreditsUsedDurationIdStatusStoppedAt
master2021-06-29T00:04:56.069Z24827743d832d004-0069-4412-8e6d-41265143411zfailed2021-06-29T02:13:59.354Z
master2021-06-28T00:04:55.409Z31299778531e678e-73e3-4f2a-ac80-55aa203461zafailed2021-06-28T02:47:52.916Z

circleci-trigger-workflow#


Triggers a new pipeline on the project.

Base Command#

circleci-trigger-workflow

Input#

Argument NameDescriptionRequired
parametersA JSON object containing pipeline parameters and their values.Required

Context Output#

PathTypeDescription
CircleCI.WorkflowTrigger.idnumberThe workflow ID.
CircleCI.WorkflowTrigger.created_atnumberDate when the workflow was created.
CircleCI.WorkflowTrigger.numbernumberThe workflow number.
CircleCI.WorkflowTrigger.statenumberThe workflow state.

Command Example#

!circleci-trigger-workflow parameters={"param1": "value"}

Context Example#

{
"CircleCI": {
"WorkflowTrigger": {
"created_at": "2021-07-28T15:49:33.906Z",
"id": "9bc69b28-f241-4918",
"number": 103232,
"state": "pending"
}
}
}

Human Readable Output#

CircleCI Workflow created successfully, ID=103232