Ellipse Gradient for Header

CircleCI Integration Guide

Connect CircleCI pipelines, workflows, jobs, artifacts, and webhook events with enterprise systems through APIs and orchestrated Martini workflows.

CircleCI integration options at a glance

CircleCI’s primary integration surface is its version 2 REST API, which supports project discovery, pipeline triggering, workflow and job monitoring, artifact retrieval, settings, and insights-related operations. CircleCI also supports webhooks for selected project, pipeline, workflow, and job events, although webhook coverage does not include every resource change. Martini can securely call these APIs, receive webhook notifications through an exposed endpoint, trigger asynchronous pipelines, and coordinate polling or reconciliation workflows. API responses are generally JSON and may be paginated. CircleCI API tokens should be stored in Martini secrets, while artifacts can be retrieved and forwarded to approved downstream storage or reporting systems.

Integration pointSupported by CircleCI?Common use casesHow Martini supports it
REST APIsYesCircleCI API v2 supports project discovery, pipeline triggering, workflow and job retrieval, cancellation or reruns, artifact listing, settings, test metadata, usage, and insights operations.Martini can consume the REST API from workflows, map JSON responses, manage pagination, and apply authentication, retry, and correlation logic.
WebhooksLimitedCircleCI provides webhook notifications for selected project, pipeline-related, workflow, and job events. Coverage does not represent every resource state change.Martini can expose an endpoint or workflow trigger, validate webhook authenticity, deduplicate events, transform payloads, and route them to downstream applications.
Pipeline triggersYesExternal systems can trigger CircleCI pipelines using a project or repository identifier, branch or tag, revision where supported, and pipeline parameters.Martini can validate approvals or release requests, call the trigger endpoint, store the pipeline ID, and coordinate subsequent status processing.
Asynchronous executionLimitedPipelines, workflows, and jobs execute asynchronously after a trigger request; no general-purpose bulk mutation API was confirmed.Martini can retain execution identifiers, poll for terminal states, use bounded backoff, and handle timeouts or duplicate requests.
File and artifact APIsLimitedCircleCI supports listing and retrieving artifacts produced by jobs, including reports, packages, logs, and deployment bundles where available.Martini can retrieve selected artifacts, transform metadata, and forward files to approved storage or release systems without treating CircleCI as general-purpose file storage.
Pagination and synchronizationYesProjects, pipelines, workflows, jobs, artifacts, and related collections may require pagination and checkpointed synchronization.Martini can use scheduled workflows, page tokens, bounded polling windows, persisted watermarks, and resource-ID deduplication.
AuthenticationYesCircleCI API v2 uses personal or project API tokens through the Circle-Token header. OAuth is available for supported application scenarios, while OIDC tokens primarily support job-to-service authentication.Martini can store tokens in protected secrets or environment configuration and keep credentials out of source code, URLs, payloads, and logs.
Database and analytics accessLimitedInsights and usage information can be accessed through CircleCI APIs where supported; direct customer database access was not confirmed.Martini can consume the relevant API endpoints and map usage or execution information into reporting and compliance systems.

How CircleCI exposes data and business events

CircleCI REST APIs

CircleCI API v2 is the primary programmatic interface for projects, pipelines, workflows, jobs, artifacts, settings, test metadata, usage, and supported insights data. Responses generally use JSON and collection endpoints may be paginated.

Martini implementation pattern

Martini implementation pattern: a workflow authenticates with a protected CircleCI token, calls the required endpoint, follows pagination or retrieves related resources, maps the response into a canonical model, and writes the result to downstream systems. Martini can also expose an API that hides CircleCI-specific request details from enterprise callers.

Implementation sequence

Authenticate with a protected CircleCI API token
Receive a request or start the scheduled synchronization
Call the required CircleCI REST endpoint
Follow pagination and retrieve related resources
Map CircleCI JSON to the target model
Apply validation, filtering, and business rulesเขers to the data

CircleCI Webhooks

CircleCI supports webhooks for selected project, pipeline-related, workflow, and job events. Webhook coverage is limited to documented event types and is not a notification for every API resource change.

Martini implementation pattern

Martini implementation pattern: an exposed Martini API endpoint or workflow trigger receives the notification, validates the configured webhook authentication or signing mechanism, deduplicates the event, enriches it with CircleCI API data when necessary, and routes it to incident, collaboration, release, or reporting systems.

Implementation sequence

Receive the CircleCI webhook notification
Validate webhook authenticity and required fields
Deduplicate using the event and CircleCI resource identifiers
Retrieve additional project or execution details when needed
Map the event to the downstream application model
Route successful and failed outcomes with correlation data

CircleCI Pipeline Triggers

CircleCI permits external systems to start pipelines through its API with a project or repository identifier, branch or tag, revision where supported, and pipeline parameters. The trigger response starts asynchronous processing and does not prove execution success.

Martini implementation pattern

Martini implementation pattern: a workflow receives an approved release or deployment request, validates environment and authorization data, calls the CircleCI trigger endpoint, stores the returned pipeline ID, and then polls or reconciles related workflows and jobs until a terminal state or timeout is reached.

Implementation sequence

Receive and validate the release or deployment request
Confirm approval, project, environment, and parameter rules
Trigger the CircleCI pipeline with the protected token
Store the pipeline ID and external correlation ID
Poll related workflows or receive supported completion events
Update the originating system with the terminal outcome

CircleCI Artifacts API

CircleCI provides API operations for listing and retrieving artifacts associated with jobs. Artifact responses can include URLs for retrieving generated files, subject to permissions and availability.

Martini implementation pattern

Martini implementation pattern: after identifying a completed job, Martini lists available artifacts, selects only approved files, retrieves them promptly, and forwards them to an object store, release system, or compliance repository while preserving CircleCI and business correlation identifiers.

Implementation sequence

Identify the completed CircleCI job
List artifacts associated with the job
Filter artifacts according to type and retention rules
Retrieve approved artifact files
Transfer files and metadata to the target system
Record transfer status and handle unavailable artifacts

Common CircleCI integration patterns

Pattern 1: Trigger an approved CircleCI release pipeline

When to use this pattern

Use this pattern when a change, release, or approval system must start a CircleCI pipeline only after business and environment checks have passed. Martini validates the request, maps release values into CircleCI pipeline parameters, prevents duplicate submissions, and reports the asynchronous result back to the originating system.

Integration direction
Jira
Martini
CircleCI
Example Mapping
CircleCI FieldCanonical FieldTarget Field
issue.keyrelease.correlationIdexternal_request_id
release.versionrelease.versionpipeline_parameters.version
deployment.environmentrelease.environmentpipeline_parameters.environment
repository.branchsource.refbranch
Martini implementation pattern

A Martini API or workflow receives the approved release request, validates authorization and required fields, checks for an existing correlation ID, calls the CircleCI pipeline trigger API, and stores the pipeline ID. A follow-up workflow polls the related workflow and job resources with backoff, then updates the originating release record and routes terminal failures to operations.

Martini capabilities used
  • APIs
  • workflows
  • authentication and secrets
  • data mapping
  • business rules
  • error handling
  • scheduled synchronization

Pattern 2: Route CircleCI failures to incident and collaboration systems

When to use this pattern

Use this pattern when selected failed jobs or workflows should create incidents, update tickets, or notify engineering channels. It is appropriate for production deployments, repeated failures, or projects with defined ownership and escalation rules.

Integration direction
CircleCI
Martini
Slack
Example Mapping
CircleCI FieldCanonical FieldTarget Field
project.slugapplication.repositorychannel.routingKey
workflow.nameexecution.workflowNamenotification.workflow
job.nameexecution.jobNameincident.component
statusexecution.outcomeincident.severity
Martini implementation pattern

Martini receives a supported CircleCI webhook, validates authenticity, deduplicates the event, and enriches it with project or workflow details when needed. Business rules select production failures, repeated failures, or deployment-related events, then create or update the relevant incident or send a normalized Slack notification. Transient downstream failures are retried without replaying the original event.

Martini capabilities used
  • API exposure
  • webhook consumption
  • data mapping
  • business rules
  • deduplication
  • error handling
  • monitoring

Pattern 3: Synchronize CircleCI execution history and artifacts

When to use this pattern

Use this pattern when a release, compliance, or reporting platform needs an authoritative view of CircleCI pipelines, workflows, jobs, and selected artifacts. Scheduled reconciliation is useful when webhook coverage is incomplete or delivery cannot be the sole source of state.

Integration direction
CircleCI
Martini
Datadog
Example Mapping
CircleCI FieldCanonical FieldTarget Field
pipeline.idexecution.pipelineIddeployment.pipeline_id
pipeline.created_atexecution.startedAtdeployment.started_at
workflow.statusexecution.outcomedeployment.status
artifact.urlexecution.artifactUrldeployment.artifact_url
Martini implementation pattern

A scheduled Martini workflow retrieves selected projects and execution resources using pagination, a bounded time window, and persisted watermarks. It deduplicates by pipeline, workflow, job, and artifact identifiers, maps status and timestamps into the target model, and transfers only approved artifacts. Rate limits and transient failures are handled with backoff and checkpointed retries.

Martini capabilities used
  • scheduled workflows
  • API consumption
  • pagination
  • data mapping
  • checkpointing
  • file handling
  • retry and error handling

Pattern 4: Orchestrate a multi-system deployment with CircleCI

When to use this pattern

Use this pattern when deployment requests require approval validation, CircleCI execution, artifact collection, and updates to a release or change process. It provides a controlled workflow around CircleCI’s asynchronous pipeline model.

Integration direction
ServiceNow
Martini
CircleCI
Example Mapping
CircleCI FieldCanonical FieldTarget Field
change.numberdeployment.changeIdpipeline_parameters.change_id
application.namedeployment.applicationproject.selection
approved.environmentdeployment.environmentpipeline_parameters.environment
pipeline.iddeployment.executionIdchange.work_notes
Martini implementation pattern

Martini receives the deployment request, validates the change and approval state, selects the permitted CircleCI project, and triggers a parameterized pipeline. It waits through polling or supported events, retrieves selected artifacts after success, updates the change record, and sends terminal failures to an operational queue. Correlation IDs and duplicate-trigger checks protect the process from retries.

Martini capabilities used
  • workflow orchestration
  • API exposure
  • API consumption
  • business rules
  • asynchronous execution
  • artifact handling
  • correlation and monitoring

Applications commonly integrated with CircleCI

CircleCI commonly participates in source-control, release, collaboration, cloud deployment, container, and observability workflows. Martini can coordinate these systems with CircleCI by consuming APIs, receiving supported events, applying business rules, and exposing controlled APIs for enterprise release processes.

Application Scenario Direction Martini Pattern
GitHub Synchronize repository and pipeline status, support pull-request workflows, and coordinate approved builds or deployments. GitHub → CircleCI → Martini Martini can receive CircleCI status events or call the CircleCI API to retrieve execution details, then map project, branch, revision, workflow, and job information for downstream reporting or release processes.
GitLab Coordinate GitLab projects and merge-request-driven automation with CircleCI pipeline execution and status reporting. GitLab → CircleCI → Martini A Martini workflow can accept an external release or merge-request event, trigger a CircleCI pipeline with project and parameter data, and reconcile the resulting pipeline and workflow status.
Bitbucket Connect Bitbucket repositories and pull-request activity with CircleCI builds and deployment workflows. Bitbucket → CircleCI → Martini Martini can orchestrate pipeline requests and status synchronization, using CircleCI identifiers and repository metadata as correlation fields for downstream systems.
Jira Associate build failures, deployment results, approvals, and release evidence with Jira issues or change records. Jira → Martini → CircleCI Martini validates Jira approval data, triggers CircleCI with release parameters, monitors the execution, and updates the originating Jira issue with the terminal result and selected artifact metadata.
Slack Deliver build and deployment notifications to engineering or operations channels and optionally route collaboration events into controlled release workflows. CircleCI → Martini → Slack Martini receives supported CircleCI webhook events, applies routing rules based on project, branch, and outcome, and sends a normalized notification to Slack while suppressing duplicate events.
AWS Coordinate CircleCI deployment jobs with AWS workloads and use suitable workload identity patterns for cloud access. CircleCI → Martini → AWS Martini can initiate or monitor CircleCI deployment pipelines and pass approved environment or release context, while CircleCI jobs perform the AWS-specific deployment using configured credentials or supported OIDC patterns.
Docker Hub Track container image build and publication outcomes and connect image artifacts with release records. CircleCI → Martini → Docker Hub After a CircleCI job completes, Martini can retrieve artifact or execution metadata, apply release rules, and update a container release process or downstream inventory.
Datadog Forward deployment, test, and pipeline metadata to observability and operational reporting processes. CircleCI → Martini → Datadog Martini can transform CircleCI webhook or API results into the required observability payload, route only relevant environments or failures, and preserve CircleCI and Martini correlation identifiers.

How to build a CircleCI integration in Martini

Objective

Configure CircleCI authentication and endpoint settings without embedding credentials in workflow logic or source-controlled mappings.

Instructions in Martini

  • Store a personal or project API token in Martini secrets or protected environment configuration.
  • Use the Circle-Token header for CircleCI API requests.
  • Apply least-privilege access and separate production credentials from lower-environment credentials.
  • Validate webhook authentication or signing requirements before accepting notifications.

Objective

Select the trigger that matches the required latency and completeness: an inbound API request, supported CircleCI webhook, or scheduled reconciliation workflow.

Instructions in Martini

  • Use an API endpoint for release or approval-driven pipeline requests.
  • Use a webhook trigger for supported job, workflow, project, or pipeline-related events.
  • Use a scheduler when authoritative state requires polling or webhook coverage is insufficient.
  • Define correlation and deduplication keys before enabling triggering.

Objective

Call CircleCI APIs or receive webhook payloads, then retrieve related resources needed to make an integration decision.

Instructions in Martini

  • Call the relevant API v2 endpoint using authenticated requests.
  • Follow pagination for projects, pipelines, workflows, jobs, or artifacts.
  • Retain pipeline, workflow, job, artifact, and external business identifiers.
  • Retrieve selected artifacts promptly when downstream processing requires them.

Objective

Coordinate validation, CircleCI calls, asynchronous execution, downstream updates, and terminal outcome handling in a maintainable Martini workflow.

Instructions in Martini

  • Validate project, environment, branch, tag, revision, and pipeline parameter rules.
  • Trigger the pipeline only after approval and duplicate-request checks pass.
  • Poll related resources with bounded backoff or process supported completion events.
  • Set timeout behavior and route terminal failures to an operational process.

Objective

Convert CircleCI JSON and webhook structures into canonical and downstream application models while preserving useful execution context.

Instructions in Martini

  • Map project, pipeline, workflow, job, artifact, status, branch, revision, and timestamp fields.
  • Normalize status values and retain CircleCI resource identifiers.
  • Ignore unknown fields and map only the data required by target systems.
  • Apply JSON transformations and enrich events with ownership or release metadata where available.

Objective

Apply enterprise controls that determine which CircleCI activity is actionable and which requests are permitted.

Instructions in Martini

  • Allow production triggers only for approved release or change requests.
  • Route failures according to project, environment, ownership, and severity.
  • Filter artifacts by type, environment, and retention policy.
  • Prevent duplicate pipeline triggers and duplicate downstream notifications.

Common CircleCI data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
OrganizationsRepresent top-level CircleCI accounts containing projects, users, settings, and policies.Identity administration, governance platforms, reporting systemsMartini retrieves organization context through the API, applies scope and ownership rules, and maps required identifiers into downstream governance models.
ProjectsRepresent source-code repositories configured for CircleCI, commonly identified by provider and repository slug.GitHub, GitLab, Bitbucket, release management, service catalogsMartini uses project identifiers and repository metadata to select pipelines, route events, and maintain synchronization checkpoints.
PipelinesRepresent executions associated with branches, tags, commits, or API-triggered requests.Jira, release systems, compliance platforms, notificationsMartini stores pipeline IDs and correlation data, triggers pipelines when authorized, and polls or reconciles their status.
WorkflowsGroup jobs within a pipeline and represent orchestration and dependency structure.Incident management, deployment records, reporting platformsMartini maps workflow status and names, evaluates terminal states, and routes failures or successful deployments according to business rules.
JobsRepresent executable units such as build, test, package, or deployment activities.Incident tools, observability platforms, compliance repositoriesMartini consumes job details and selected events, deduplicates by stable identifiers, and enriches failures with project and ownership data.
ArtifactsRepresent files produced by jobs, including test reports, packages, logs, or deployment bundles.Object storage, release management, document repositories, audit systemsMartini lists and retrieves selected artifacts, transfers them promptly when needed, and stores metadata rather than embedding large files in messages.

Authentication and security considerations

Token-based API access

CircleCI API v2 uses personal or project API tokens, commonly supplied in the Circle-Token header. Token permissions depend on token type and CircleCI organization configuration.

Secrets and workload identity

Store CircleCI tokens in Martini secrets or protected environment configuration. CircleCI OIDC job tokens primarily support jobs authenticating to external services and are not the general authentication method for Martini calling CircleCI.

Webhook protection

Validate the authentication or signing mechanism configured for each CircleCI webhook before processing events. Reject malformed, unexpected, or unauthenticated notifications.

Operational security

  • Use least-privileged project credentials where practical.
  • Mask tokens, pipeline parameters, environment variables, artifacts, and sensitive job output in logs.
  • Keep production deployment credentials separate from lower-environment credentials.
  • Record correlation identifiers without exposing secrets.

Operational considerations for CircleCI integrations

Rate limits and pagination

CircleCI API requests may be rate limited, and collection endpoints may be paginated. Martini workflows should use bounded pagination, centralized throttling, checkpointing, and exponential backoff for temporary failures such as HTTP 429 responses.

Asynchronous execution

A successful pipeline-trigger response does not mean the pipeline or deployment succeeded. Store the pipeline ID, monitor related workflows and jobs, define terminal states, and enforce timeouts.

Idempotency and reconciliation

Use pipeline, workflow, job, artifact, and webhook event identifiers as deduplication keys. Combine webhook processing with scheduled reconciliation for unsupported events, missed deliveries, or authoritative status checks.

Schema and artifact handling

Map only required fields and tolerate unknown JSON properties. Artifact URLs may be temporary or authorization-dependent, so retrieve approved artifacts promptly and transfer them to approved storage when required.

Testing and monitoring

Test authentication failures, permission boundaries, invalid parameters, rate limits, duplicate events, timeouts, and pipeline failures. Retain CircleCI and Martini correlation IDs and monitor workflow logs without recording credentials.

Why use Martini instead of scripts or point-to-point integrations?

Centralized orchestration

Martini provides a workflow layer for approvals, CircleCI pipeline triggers, asynchronous status checks, artifact retrieval, downstream updates, and operational escalation instead of scattering logic across scripts.

Reusable integration logic

Reusable workflows can standardize authentication, pagination, retries, deduplication, status normalization, and correlation across multiple CircleCI projects and enterprise processes.

Controlled APIs and transformations

Martini can expose an API façade that hides CircleCI-specific details from release, change, or service-catalog callers while mapping CircleCI JSON into stable canonical and downstream formats.

Maintainability and visibility

Centralized business rules, protected configuration, error handling, and workflow monitoring make changes easier to govern than independent point-to-point scripts. Martini can combine webhooks with scheduled reconciliation when CircleCI event coverage is incomplete.

Frequently asked questions

How can CircleCI be integrated with enterprise systems?

CircleCI can be integrated through its version 2 REST API, supported webhooks, and API-based pipeline triggers. Enterprise workflows can start pipelines, monitor pipelines, workflows, and jobs, retrieve artifacts, synchronize execution data, and route selected events to release, incident, collaboration, reporting, or compliance systems.

Can Martini integrate with CircleCI?

Yes. Martini can consume the CircleCI REST API, receive supported CircleCI webhook events through an exposed API or workflow trigger, trigger pipelines, synchronize execution state, retrieve artifacts, and transform CircleCI data for downstream systems.

Do I need a connector to integrate CircleCI with Martini?

No dedicated CircleCI connector is required. Martini can integrate with CircleCI using its native REST API, supported webhooks, pipeline trigger endpoints, token authentication, and artifact API through workflows and APIs.

Is there any extra Lonti cost to integrate CircleCI with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate CircleCI. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from CircleCI, cloud infrastructure, storage, or other third-party systems depending on subscriptions, usage, and deployment model.

Which CircleCI integration methods should architects use?

Use the CircleCI API v2 as the primary integration surface for projects, pipeline triggers, workflows, jobs, artifacts, settings, and supported insights data. Use webhooks for documented low-latency events, and scheduled API reconciliation when webhook coverage is incomplete or authoritative status is required. No official CircleCI GraphQL or SOAP API was confirmed.

Can CircleCI send events or callbacks to Martini?

CircleCI supports webhooks for selected project, pipeline-related, workflow, and job events. Martini can expose an endpoint to receive and validate these notifications. Because webhook coverage is limited to documented events, polling or scheduled reconciliation may still be needed.

How does synchronization with CircleCI work?

Martini can use webhooks for supported events or scheduled workflows that retrieve paginated projects, pipelines, workflows, jobs, artifacts, and insights-related data. Synchronization should persist watermarks or execution identifiers, use bounded polling windows where necessary, and deduplicate by stable CircleCI resource IDs.

How does Martini handle CircleCI errors, retries, and duplicate events?

Martini can distinguish authentication, permission, rate-limit, validation, transport, and pipeline-execution failures. Transient API failures can use bounded retries and exponential backoff, while non-idempotent pipeline triggers require correlation and duplicate-request checks. Webhook events should be deduplicated using stable event and resource identifiers.

Related Martini documentation

CircleCI APIs

Events

Data handling

Security

Operations

Connect CircleCI to your enterprise workflows

Use Martini to orchestrate CircleCI pipelines, consume execution data, receive supported webhook events, and synchronize delivery outcomes across your enterprise systems.

EXPLORE MARTINI
BOOK A DEMO