Skip to main content

Run EventCatalog Federation in CI

View as Markdown
EventCatalog Enterprise Feature

Run Federation before the normal EventCatalog build so the generated organization view exists when EventCatalog renders the site.

Add explicit scripts​

Add separate and combined scripts to the central catalog:

package.json
{
  "scripts": {
    "federate": "eventcatalog federate",
    "build": "eventcatalog build",
    "build:federated": "npm run federate && npm run build"
  }
}

Keeping federate and build separate makes it clear which stage failed. The combined script is useful for deployment platforms that accept one build command.

Provide your Enterprise license and repository tokens​

Federation requires an EventCatalog Enterprise offline license. Email hello@eventcatalog.dev to request a trial key.

The simplest option is to commit license.jwt in the central catalog root. Federation will find it automatically when CI runs. If your organization prefers not to commit the file, store its contents in your CI provider and write license.jwt during the job. Set EC_LICENSE only when you write the file somewhere other than the catalog root.

Provide these environment variables when needed:

VariableWhen it is needed
EC_LICENSEOptional path to the Enterprise offline license file when it is not stored at ./license.jwt
EVENTCATALOG_GITHUB_TOKENRecommended for private GitHub sources
GITHUB_TOKENUsed as a fallback when EVENTCATALOG_GITHUB_TOKEN is not set

GitHub tokens need read access to the configured repositories. Store those tokens in your CI provider's secret store rather than in eventcatalog.config.js.

Run the pipeline​

The CI sequence is:

npm ci
npm run federate
npm run build

or:

npm ci
npm run build:federated

Choose moving or immutable refs​

A branch such as main makes CI pick up new source commits whenever Federation runs. This is useful when the organization catalog should continuously follow each team.

An exact commit SHA makes the configured source repeatable:

eventcatalog.config.js
{
  id: 'acme/payments',
  source: 'github:acme/payments-catalog',
  ref: '4a1b7e23c79b4ef9f5f337c5e7655a5ec82a4761',
}

eventcatalog.lock records the source state selected by a completed run, but it does not control the next run. Use immutable ref values when repeatability is required.

Decide which warnings should block CI​

Promote important warning rules to error in the central configuration:

eventcatalog.config.js
export default {
  federation: {
    rules: {
      'federation/missing-resource': 'error',
      'federation/unresolved-version': 'error',
    },
    sources: [/* ... */],
  },
};

This makes the federation command return an error before installing new output when a configured rule is violated.

Review Configure validation rules before changing structural errors to warnings.

Cache downloaded content​

Federation stores verified content in .eventcatalog-cache/federation/content/. Persisting .eventcatalog-cache with your CI cache can reduce repeated downloads.

Treat the cache as disposable. Federation checks content hashes before reuse and downloads content again when a valid entry is unavailable.

Use --no-cache when investigating a cache problem:

npm run federate -- --no-cache

Preserve useful failure output​

Errors always include their details. Warning details require --verbose:

npm run federate -- --verbose

Consider using verbose output in CI while Federation is being introduced, then switch back to the concise output if the logs become noisy.

Next steps​