Warning
This project is deprecated and will not receive further updates.
Atlassian has announced the end of Compass. Compass reaches end-of-sale on May 13, 2026, renewals end December 31, 2026, and product support concludes in December 2027. Atlassian is directing customers to migrate to DX.
Since this generator has no known production users, development is being wound down ahead of Atlassian's timeline. The package will remain published for existing installs, but no new features or non-critical fixes will be shipped. If you depend on this plugin, please pin the current version and plan a migration away from Compass.
An EventCatalog generator plugin that creates services from Atlassian Compass components. It supports two modes: reading local compass.yml files (YAML mode) or fetching components directly from the Compass GraphQL API (API mode).
npm install @ismaelmartinez/generator-atlassian-compass-event-catalogAdd the generator to your eventcatalog.config.js. The plugin supports two mutually exclusive modes: YAML mode (local files) and API mode (Compass GraphQL API).
Read services from local compass.yml files:
generators: [
[
'@ismaelmartinez/generator-atlassian-compass-event-catalog',
{
services: [
{
path: 'path/to/compass.yml',
version: '1.0.0', // optional, defaults to '0.0.0'
id: 'custom-id', // optional, defaults to the name in the compass file
},
],
compassUrl: 'https://your-site.atlassian.net/compass',
},
],
],Fetch components directly from the Compass GraphQL API:
generators: [
[
'@ismaelmartinez/generator-atlassian-compass-event-catalog',
{
api: {
cloudId: '$COMPASS_CLOUD_ID', // supports $ENV_VAR syntax
apiToken: '$COMPASS_API_TOKEN',
email: '$COMPASS_EMAIL',
baseUrl: 'https://your-site.atlassian.net', // must be HTTPS
typeFilter: ['SERVICE', 'APPLICATION'], // optional, server-side filtering
},
compassUrl: 'https://your-site.atlassian.net/compass',
},
],
],API mode credentials support $ENV_VAR syntax, so you can reference environment variables rather than hardcoding secrets.
| Option | Type | Default | Description |
|---|---|---|---|
services |
ServiceOptions[] |
- | YAML mode: array of local compass file paths |
api |
ApiConfig |
- | API mode: Compass GraphQL API connection config |
compassUrl |
string |
(required) | Base URL for Compass component links |
domain |
DomainSpec | DomainMapping |
- | Associate services with a domain (static, or derived from metadata) |
typeFilter |
string[] |
- | Only process components matching these type IDs |
nameFilter |
string[] |
- | Only process components whose name matches one of these strings |
nameMapping |
Record<string, string> |
- | Map Compass component names to custom service IDs |
overrideExisting |
boolean |
true |
Whether to update existing services or skip them |
debug |
boolean |
false |
Enable debug logging (credentials are redacted) |
format |
'md' | 'mdx' |
'mdx' |
Output file format |
serviceIdStrategy |
'name' | 'compass-id' | Function |
'name' |
How service IDs are derived |
markdownTemplate |
Function |
- | Custom function to generate service markdown content |
dryRun |
boolean |
false |
Log what would happen without writing any changes |
defaultVersion |
string |
'0.0.0' |
Default version for services that don't specify one |
badges |
boolean |
true |
Generate badges from Compass metadata (type, lifecycle, tier, labels) |
incremental |
boolean |
false |
Skip writing services unchanged since the previous run (hash manifest) |
See the example configuration for a complete working setup.
All Compass component types are supported: SERVICE, APPLICATION, LIBRARY, CAPABILITY, CLOUD_RESOURCE, DATA_PIPELINE, MACHINE_LEARNING_MODEL, UI_ELEMENT, WEBSITE, and OTHER. Each component is written as an EventCatalog service entry. Use typeFilter to restrict which types are processed.
DEPENDS_ON relationships defined in Compass are resolved to links between EventCatalog services. Dependencies are resolved across all services processed in the same generator run, and unresolvable ARNs are logged and skipped gracefully.
Services receive color-coded badges based on their Compass metadata: component type (e.g. SERVICE, APPLICATION), lifecycle stage (Active, Pre-release, Deprecated), tier level (1-4), labels, and scorecard scores (green/amber/red based on percentage). Scorecard badges show the score name and percentage. Set badges: false to disable badge generation entirely.
When a component has an ownerId, the generator extracts the team UUID and creates an EventCatalog team entity. In API mode, the team's display name is fetched from Compass; in YAML mode the UUID is used as the name. Teams are deduplicated across services.
Links with names containing "openapi" or "swagger" are attached as OpenAPI specifications, and links with "asyncapi" are attached as AsyncAPI specifications. This allows EventCatalog to render API documentation alongside service pages.
Provide a markdownTemplate function to fully control the markdown content generated for each service. The function receives the CompassConfig, resolved dependencies, and structured links extracted from the Compass config (URL, title, category, icon, raw type):
markdownTemplate: (config, dependencies, links) => {
const deps = dependencies.map((d) => d.name).join(', ') || 'none';
const repo = links?.find((l) => l.rawType === 'REPOSITORY')?.url ?? '';
return `# ${config.name}\n\nDeps: ${deps}\n\nRepo: ${repo}`;
},The links parameter is optional, so existing two-argument templates still work. Import the StructuredLink type from the package root if you want type hints.
Control how service IDs are derived with serviceIdStrategy:
'name'(default): uses the component name from Compass'compass-id': uses the Compass ARN (sanitized for filesystem safety)- Custom function:
(config) => stringfor full control
File-level id overrides in YAML mode always take precedence over the strategy.
Set dryRun: true to see what the generator would do without writing any files. Services, teams, and domain associations are all logged but not persisted.
Set incremental: true to skip writing services that haven't changed since the last run. The generator computes a SHA-256 hash of each built service and stores it in .compass-hashes.json in the project directory. On subsequent runs, services with a matching hash are skipped and reported in the summary as Skipped (unchanged).
The generator continues processing when individual services fail (e.g. malformed YAML, missing files). A summary at the end reports succeeded and failed counts with error details.
When a domain option is provided, generated services are associated with a domain. Domains are created automatically when first used, and versioned when their version string changes between runs.
Static domain — all services go to the same domain:
domain: { id: 'payments', name: 'Payments', version: '0.0.1' }Derived from a Compass label — first matching label wins (case-sensitive):
domain: {
from: 'label',
mapping: {
backend: { id: 'backend', name: 'Backend', version: '0.0.1' },
frontend: { id: 'frontend', name: 'Frontend', version: '0.0.1' },
},
fallback: { id: 'other', name: 'Other', version: '0.0.1' }, // optional; default is 'skip'
}Derived from a custom field value:
domain: {
from: 'customField',
key: 'platform',
mapping: {
web: { id: 'web-platform', name: 'Web Platform', version: '0.0.1' },
mobile: { id: 'mobile-platform', name: 'Mobile Platform', version: '0.0.1' },
},
fallback: 'skip', // unmatched services get no domain association
}Each mapped domain is versioned independently — bumping one domain's version in config won't re-version the others.
All user-controlled text is sanitized before embedding in markdown/MDX output. sanitizeMarkdownText escapes HTML special characters and markdown link syntax, and sanitizeUrl only allows http: and https: protocols (preventing javascript: and data: URI injection). Local spec file paths referenced by OpenAPI/AsyncAPI links are passed through sanitizeLocalPath, which rejects absolute paths and ../ traversal sequences. Shared helpers in sanitize.ts (sanitizeHtml, sanitizeId) are used for service/team IDs and for custom field text values returned by the Compass API. In API mode, the baseUrl is validated to require HTTPS, and debug logging redacts API tokens and email addresses.
Raise a GitHub issue on this project, or contact us on our Discord server.
See LICENSE.
See the CONTRIBUTING.md file for more information.