.png)
Atlassian Compass Integration Guide
Integrate Atlassian Compass with enterprise systems through its REST APIs, supported events, and scheduled Martini workflows.
Atlassian Compass integration options at a glance
Atlassian Compass provides documented REST APIs for working with catalog resources and related data, plus an Events API for supported engineering and operational signals such as deployment activity. Atlassian Cloud authentication can use API-token Basic Authentication or OAuth 2.0, subject to permissions and scopes. A general Compass outbound webhook facility, public GraphQL API, SOAP API, bulk API, and direct database access were not confirmed. Martini can consume Compass REST endpoints, submit supported events, expose APIs for CI/CD systems, schedule polling workflows, map payloads, apply validation and business rules, and handle pagination, rate limits, retries, and checkpoints.
| Integration point | Supported by Atlassian Compass? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Retrieve, create, update, and associate supported Compass catalog resources, including Components and Teams, subject to the current API schema and permissions. | Martini can consume Compass REST endpoints from workflows, map request and response payloads, expose reusable APIs, and apply validation, retries, and error handling. |
| Events API | Yes | Send supported engineering and operational signals, such as deployment or lifecycle events, into Compass from CI/CD and operational systems. | Martini can receive normalized event requests, enrich and validate them, and submit supported Compass event payloads while tracking correlation and duplicate keys. |
| Webhooks / outbound callbacks | Not confirmed | A generally available Compass-specific outbound webhook facility for component, team, scorecard, or metric changes was not confirmed. | Martini can expose REST APIs for other systems and can use scheduled polling or an Atlassian-supported notification mechanism where one is available for the particular use case. |
| Authentication | Yes | Authenticate to Atlassian Cloud with API-token Basic Authentication or OAuth 2.0, subject to account permissions and configured scopes. | Martini stores site URLs, credentials, tokens, and scopes in secure configuration or secrets and uses them when invoking Compass APIs. |
| Pagination | Yes | List operations may return paginated Compass resources, so catalog synchronization must continue until all pages are processed. | Martini workflows can loop through pages, maintain checkpoints, bound work, and avoid assuming that one response contains the full catalog. |
| Bulk / async / batch APIs | Not confirmed | A general-purpose Compass bulk or asynchronous REST API was not confirmed for new integrations. | Martini can implement bounded batches over documented REST operations with rate-limit handling and checkpointing rather than assuming a bulk endpoint. |
| GraphQL APIs | Not confirmed | A public Compass GraphQL API was not confirmed in the reviewed documentation; REST is the recommended integration surface. | Martini can consume GraphQL APIs generally, but a Compass integration should use the documented REST API unless Atlassian publishes a supported GraphQL endpoint. |
| SOAP APIs | No | No Compass SOAP API was identified in the reviewed vendor documentation. | Martini can consume SOAP services generally, but SOAP is not an appropriate integration method for Compass based on the supplied research. |
| Database access | No | Direct database or analytics access to Compass Cloud is not a supported integration approach. | Martini should consume Atlassian's public APIs rather than connecting directly to Compass storage. |
How Atlassian Compass exposes data and business events
Atlassian Compass REST APIs
Compass exposes REST resources for interacting with catalog and related Compass data. Depending on the resource and operation, integrations can retrieve, create, update, or associate supported information. The current Compass API schema should be treated as authoritative because UI concepts may not have identical REST representations.
Martini implementation pattern
Martini implementation pattern: a workflow authenticates to Atlassian Cloud, calls the relevant Compass REST endpoint, handles pagination and status codes, maps the response into a canonical model, and writes or exposes the result to another system. For writes, the workflow validates required fields, applies deterministic matching, and records identifiers for future synchronization.
Implementation sequence
Atlassian Compass Events API
Compass provides an events mechanism for supported engineering and operational signals, including deployment or other software lifecycle events. It is not a universal outbound webhook stream, so event names, required fields, supported categories, and processing behavior must be checked against the current documentation.
Martini implementation pattern
Martini implementation pattern: CI/CD or operational systems call a Martini API with a normalized event, or Martini retrieves source events on a schedule. Martini validates the Component association and event type, enriches the payload, submits it to the Compass Events API, and retains a correlation or source event key for troubleshooting and duplicate control.
Implementation sequence
Scheduled Compass synchronization
A general Compass outbound webhook facility was not confirmed. Scheduled synchronization is therefore a practical approach for detecting changes in Components, Teams, or other supported REST resources when a source system or use case requires polling.
Martini implementation pattern
Martini implementation pattern: a scheduler starts a workflow that reads the last checkpoint, requests paginated Compass data, compares stable identifiers and relevant fields, and sends changes to the target system. The workflow uses bounded requests, rate-limit backoff, checkpoint persistence, and explicit handling for deleted or inaccessible resources.
Implementation sequence
Common Atlassian Compass integration patterns
Pattern 1: Synchronize a service catalog into Compass
When to use this pattern
Use this pattern when an existing service catalog or application inventory is authoritative for service names, descriptions, ownership, repositories, or lifecycle status and Compass is the developer-facing catalog.
Integration direction
Example Mapping
| Atlassian Compass Field | Canonical Field | Target Field |
|---|---|---|
| Source service identifier | component.externalId | Compass Component identifier or external reference |
| Service name and description | component.name and component.description | Compass Component metadata |
| Technical owner | component.ownerTeam | Compass Team association |
| Repository or deployment URL | component.links | Supported Compass component link or metadata field |
Martini implementation pattern
A scheduled Martini workflow retrieves source services, resolves stable Component identity, validates Team references, transforms fields to the documented Compass schema, and performs create or update operations. It stores source-to-Compass identifiers, uses idempotent matching to prevent duplicates, and retries transient failures without advancing the checkpoint prematurely.
Martini capabilities used
- workflows
- scheduled triggers
- API consumption
- data mapping
- business rules
- error handling
Pattern 2: Publish CI/CD deployment events to Compass
When to use this pattern
Use this pattern when multiple delivery tools need to publish consistent deployment outcomes to Compass and the source systems do not share the same event structure.
Integration direction
Example Mapping
| Atlassian Compass Field | Canonical Field | Target Field |
|---|---|---|
| deployment status | deployment.status | Supported Compass event status |
| repository and revision | deployment.source | Compass event source fields |
| environment | deployment.environment | Compass event environment field |
| service identifier | deployment.componentId | Compass Component association |
Martini implementation pattern
CI/CD systems call a Martini API after deployment completion. Martini validates the source event, enriches it with repository and environment context, maps success, failure, or rollback statuses where supported, and submits the documented Compass event. Source event identifiers are retained for duplicate detection, while transient API failures use bounded retries and backoff.
Martini capabilities used
- APIs
- workflows
- data mapping
- validation
- business rules
- error handling
- reusable integration assets
Pattern 3: Reconcile ownership and Teams
When to use this pattern
Use this pattern when identity, HR, service-management, or engineering systems govern team membership and ownership while Compass presents the resulting responsibility model to developers.
Integration direction
Example Mapping
| Atlassian Compass Field | Canonical Field | Target Field |
|---|---|---|
| Team identifier | team.externalId | Compass Team identity |
| Team name | team.name | Compass Team name |
| Responsible group | component.ownerTeam | Compass Component ownership |
| Membership status | team.memberStatus | Supported Compass team membership or related field |
Martini implementation pattern
Martini periodically retrieves authoritative team data, matches Teams by stable identifiers, validates that referenced Teams exist, and reconciles Component ownership. The workflow separates missing references from authorization failures, avoids overwriting non-authoritative metadata, and records rejected ownership changes for review.
Martini capabilities used
- scheduled workflows
- API consumption
- data mapping
- validation
- business rules
- monitoring
Pattern 4: Aggregate engineering signals for Component health
When to use this pattern
Use this pattern when delivery, monitoring, or incident systems provide signals that should be normalized and associated with Compass Components, subject to the metrics and event types Compass currently supports.
Integration direction
Example Mapping
| Atlassian Compass Field | Canonical Field | Target Field |
|---|---|---|
| External service identifier | component.externalId | Compass Component association |
| Deployment or incident signal | engineeringEvent.type | Supported Compass event type |
| Health measurement | componentMetric.value | Supported Compass Metric field |
| Observed timestamp | engineeringEvent.occurredAt | Compass event timestamp |
Martini implementation pattern
Martini retrieves selected signals, applies organization-specific thresholds and component matching, and sends only supported Compass metrics or events. The workflow preserves source identifiers, rejects unsupported payload shapes, handles rate limits, and logs the mapping decision so operational teams can distinguish accepted signals from source-only data.
Martini capabilities used
- workflows
- API consumption
- data transformation
- business rules
- validation
- error handling
Applications commonly integrated with Atlassian Compass
Compass can be integrated with development, delivery, source-control, observability, and incident-management products through their documented APIs or event mechanisms. Martini provides a controlled orchestration layer for normalizing data before it is written to Compass; the applications below are not evidence of dedicated native Compass connectors.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Jira Software | Associate Compass Components with development work, incidents, and delivery activity while providing engineering context across Atlassian systems. | Jira Software → Martini → Atlassian Compass | Martini retrieves selected Jira Software data, validates component and team references, maps issue or delivery context to supported Compass fields or events, and records failures for retry. The exact Compass-Jira capability should be verified against the current Compass API. |
| Bitbucket | Associate repositories and delivery activity with Compass Components and publish relevant development or deployment signals. | Bitbucket → Martini → Atlassian Compass | A Martini workflow receives or polls Bitbucket data, resolves the corresponding Compass Component, normalizes repository and deployment information, and submits supported REST or event payloads with idempotent handling. |
| GitHub | Connect repository ownership and engineering activity with Compass catalog entries and forward supported CI/CD or repository events. | GitHub → Martini → Atlassian Compass | Martini consumes GitHub APIs or callbacks where available, maps repository identifiers and ownership to Compass Components, validates required event fields, and sends supported Compass events while applying retry and duplicate safeguards. |
| GitLab | Publish repository, pipeline, and deployment information to Compass for teams using GitLab for source control and CI/CD. | GitLab → Martini → Atlassian Compass | Martini receives GitLab event data or performs scheduled retrieval, converts it to a canonical deployment model, enriches it with Compass component identity, and submits only event types supported by the current Compass API. |
| Jenkins | Send build and deployment outcomes to Compass and associate delivery activity with software catalog Components. | Jenkins → Martini → Atlassian Compass | Jenkins calls a Martini API after a build or deployment, Martini validates the event, enriches environment and repository details, maps success or failure status, and submits the supported Compass event with correlation and retry handling. |
| Datadog | Combine monitoring or service-health signals with Compass component ownership and catalog information. | Datadog → Martini → Atlassian Compass | Martini retrieves selected Datadog signals, applies organization-specific thresholds and component matching, and publishes only metrics or events supported by Compass. Unsupported health concepts remain in the source system rather than being forced into Compass fields. |
| PagerDuty | Relate incidents and operational ownership to Compass Components and Teams. | PagerDuty → Martini → Atlassian Compass | Martini consumes PagerDuty incident data, resolves the affected Compass Component and Team, applies routing and deduplication rules, and sends a supported Compass event or updates supported catalog data. |
How to build a Atlassian Compass integration in Martini
Objective
Establish the Atlassian Cloud connection and keep credentials, site URLs, tokens, and scopes outside workflow definitions.
Instructions in Martini
- Configure the Compass site URL in environment settings
- Choose API-token Basic Authentication or OAuth 2.0 based on the access model
- Store tokens and client credentials in Martini secrets
- Confirm Compass permissions and required OAuth scopes
Objective
Select an event-driven or scheduled entry point based on the source system and Compass notification coverage.
Instructions in Martini
- Use a Martini API for CI/CD or operational systems that can call back
- Use a scheduler for Compass polling because general outbound webhooks were not confirmed
- Define the synchronization interval and checkpoint strategy
- Limit polling to the resources and fields required
Objective
Read documented Compass resources or accept normalized source events before processing them.
Instructions in Martini
- Call the relevant Compass REST endpoint
- Follow pagination until all required results are retrieved
- Capture response status, correlation identifiers, and source keys
- Respect rate limits and Retry-After responses
Objective
Coordinate source retrieval, enrichment, validation, Compass calls, and target-system writes as one maintainable integration flow.
Instructions in Martini
- Separate retrieval, transformation, validation, and write stages
- Resolve Component and Team identity before dependent operations
- Use conditional routing for create, update, skip, and failure cases
- Persist checkpoints only after successful processing
Objective
Convert source-specific payloads into documented Compass Components, Teams, Metrics, or Events while keeping vendor and canonical models distinct.
Instructions in Martini
- Create explicit field mappings for each Compass resource
- Normalize identifiers, timestamps, status values, and ownership references
- Preserve source identifiers for reconciliation
- Validate required fields and reject unsupported event types
Objective
Enforce ownership, duplicate, authorization, and data-quality decisions before writing to Compass.
Instructions in Martini
- Define the authoritative source for each field
- Check whether a Component or Team already exists before creating it
- Detect repeated deployment events using a source event key where available
- Route missing references and validation failures for review
Common Atlassian Compass data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Components | Catalog software services, applications, libraries, websites, and other engineering-owned assets with metadata, ownership, and links. | Service catalogs, Jira Software, Bitbucket, GitHub, GitLab, monitoring platforms | Martini maps source service identifiers, names, descriptions, owners, repositories, URLs, and lifecycle values to documented Compass fields, using idempotent matching and stable identifiers. |
| Teams | Represent groups responsible for Components and engineering work. | Identity systems, HR platforms, Jira Software, service catalogs | Martini validates team references before changing ownership, reconciles authoritative team data, and handles missing or unauthorized Teams as explicit workflow errors. |
| Scorecards | Evaluate whether Components meet defined engineering standards or criteria. | Engineering governance platforms, service catalogs, reporting systems | Martini can retrieve supported scorecard data for reporting or apply source-side rules before updating supported Compass resources; it should not assume every UI concept is a writable API field. |
| Metrics | Represent health or engineering measurements associated with Components. | Datadog, monitoring platforms, delivery platforms, reporting systems | Martini normalizes selected external measurements and publishes only metrics supported by the Compass API, preserving unsupported measurements in the source system. |
| Events | Capture supported development and operational signals, including deployment or lifecycle activity. | Jenkins, GitHub, GitLab, Bitbucket, CircleCI, PagerDuty | Martini receives or polls source events, validates required fields, enriches Component identity and environment data, submits supported event payloads, and prevents duplicate processing where an event key is available. |
Authentication and security considerations
Use Atlassian Cloud authentication
Compass integrations can use an Atlassian API token with Basic Authentication over HTTPS or OAuth 2.0 for delegated application access. Authentication does not replace Compass permissions or OAuth scope checks.
Protect credentials and limit access
- Store API tokens, OAuth client credentials, access tokens, refresh tokens, account email addresses, and site URLs in Martini secrets or secure environment configuration.
- Use a dedicated Atlassian account where API-token authentication is appropriate.
- Request only the OAuth scopes and Compass permissions required by the workflow.
- Exclude tokens and other secrets from logs and error payloads.
Operational considerations for Atlassian Compass integrations
Rate limits and pagination
Atlassian Cloud APIs may enforce rate limits. Detect HTTP 429 responses, honor Retry-After when provided, use bounded backoff, and avoid unnecessary full-catalog reads. Process paginated Compass responses until the API indicates completion.
Idempotency and checkpoints
Store stable source identifiers alongside Compass identifiers, check for existing Components before creation, and retain source event keys where available. Persist checkpoints only after successful writes so interrupted workflows can resume safely.
Schema and event coverage
Keep mappings aligned with the documented Compass API rather than UI-only concepts. Validate required fields and supported event types, monitor non-success responses, and version mappings when the Compass schema changes.
Testing and ownership
Test authorization, missing Teams, invalid payloads, duplicate events, rate limiting, and transient failures. Define authoritative systems for Component metadata, Team ownership, repository links, deployment status, metrics, and scorecard-related data before enabling bidirectional synchronization.
Why use Martini instead of scripts or point-to-point integrations?
Centralized orchestration
Martini provides a maintainable workflow layer between Compass and development, delivery, identity, monitoring, and incident systems. It separates API calls, transformations, business rules, and target writes instead of embedding logic in isolated scripts.
Reusable integration behavior
Teams can expose a controlled Martini API for normalized CI/CD events, reuse mappings and validation logic, and implement scheduled synchronization when Compass does not provide the required outbound notification.
Operational reliability
- Handle pagination, rate limits, retries, checkpoints, and duplicate detection consistently.
- Keep credentials in secure configuration rather than source code or workflow payloads.
- Log correlation data and processing outcomes while excluding sensitive values.
- Apply explicit ownership and schema rules as Compass and surrounding systems evolve.
Frequently asked questions
Atlassian Compass can be integrated through its documented REST APIs and supported Events API. Enterprise workflows can synchronize Components and Teams, publish supported deployment or lifecycle events, and use Atlassian API-token Basic Authentication or OAuth 2.0. Where outbound Compass notifications are unavailable, scheduled polling can support synchronization.
Yes. Martini can consume the Atlassian Compass REST API, send supported Compass events, expose APIs for CI/CD and operational systems, and orchestrate scheduled synchronization. It can also map data, apply validation and business rules, and handle pagination, rate limits, retries, and errors.
No. A dedicated Atlassian Compass connector is not required. Martini can integrate using Compass REST APIs, the supported Events API, Atlassian authentication methods, and scheduled workflows where polling is needed. A native Martini Compass connector was not confirmed in the supplied research.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Atlassian Compass with Martini. Integrations are subject to the provisioned capacity of the Martini environment. Separate costs may apply from Atlassian, infrastructure providers, or other third-party systems based on their subscriptions, usage, and deployment models.
The documented Compass REST APIs are the primary integration surface for catalog and related resources. The Compass Events API is appropriate for supported engineering and operational signals. A public Compass GraphQL API, SOAP API, general bulk API, and direct database access were not confirmed or supported in the reviewed research.
Compass provides an Events API for sending supported engineering and operational events into Compass, but a general Compass-specific outbound webhook facility was not confirmed. Martini can expose an API for external systems and can poll Compass on a schedule. Any Atlassian notification mechanism must be verified for the particular resource and event.
Martini can retrieve paginated Components, Teams, or other supported resources, map them to a canonical model, and write them to another system or back to Compass. Stable source identifiers, explicit field mappings, authoritative ownership rules, checkpoints, and idempotent create-or-update logic help prevent duplicates and unintended overwrites.
A Martini workflow can distinguish authentication, authorization, validation, missing-reference, rate-limit, transient-service, and duplicate errors. It can honor Retry-After, use bounded backoff, log correlation identifiers without secrets, retain source event keys, and advance synchronization checkpoints only after successful processing. Martini can also expose an API façade for systems that need a controlled endpoint for normalized Compass data or events.
Related Martini documentation
Workflows
Operations
Integrate Atlassian Compass with Martini
Use Martini to connect Atlassian Compass REST APIs and supported events with your enterprise systems through secure, observable workflows.