# Run EventCatalog Federation in CI

Copy as Markdown[View as Markdown](/docs/federation/how-to/run-in-ci.md)

***

`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-explicit-scripts "Direct link to 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.

## Configure secrets[​](#configure-secrets "Direct link to Configure secrets")

Provide these environment variables to CI:

| Variable                         | When it is needed                                              |
| -------------------------------- | -------------------------------------------------------------- |
| `EVENTCATALOG_SCALE_LICENSE_KEY` | Required to use Federation                                     |
| `EVENTCATALOG_GITHUB_TOKEN`      | Recommended for private GitHub sources                         |
| `GITHUB_TOKEN`                   | Used as a fallback when `EVENTCATALOG_GITHUB_TOKEN` is not set |

Tokens need read access to the configured repositories. Store them in your CI provider's secret store rather than in `eventcatalog.config.js`.

## Run the pipeline[​](#run-the-pipeline "Direct link to 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[​](#choose-moving-or-immutable-refs "Direct link to 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[​](#decide-which-warnings-should-block-ci "Direct link to 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](/docs/federation/how-to/configure-validation-rules.md) before changing structural errors to warnings.

## Cache downloaded content[​](#cache-downloaded-content "Direct link to 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[​](#preserve-useful-failure-output "Direct link to 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[​](#next-steps "Direct link to Next steps")

* [Configure GitHub sources](/docs/federation/how-to/configure-github-sources.md)
* [Configure validation rules](/docs/federation/how-to/configure-validation-rules.md)
* [Understand the lockfile and cache](/docs/federation/explanation/lockfile-and-cache.md)