# Federation lockfile and content cache

Copy as Markdown[View as Markdown](/docs/federation/explanation/lockfile-and-cache.md)

***

`EventCatalog Enterprise Feature`

Federation writes two kinds of local state:

* `eventcatalog.lock` records the source state and managed public files from a completed run.
* `.eventcatalog-cache/` stores verified content that can be reused by later runs.

They solve different problems.

## What the lockfile records[​](#what-the-lockfile-records "Direct link to What the lockfile records")

For each source, `eventcatalog.lock` records:

* The stable source ID
* The Git commit or content-derived local revision used by the run
* A digest of the resolved source index
* The time the source was resolved

It also records the hash and source of public files managed by Federation. This allows a later run to update or remove generated public files without deleting files owned or modified by the central catalog.

A simplified lockfile looks like:

eventcatalog.lock

```
{
  "lockVersion": 1,
  "sources": [
    {
      "id": "acme/payments",
      "digest": "sha256:...",
      "commit": "4a1b7e23c79b4ef9f5f337c5e7655a5ec82a4761",
      "resolvedAt": "2026-08-21T10:30:00.000Z"
    }
  ],
  "publicFiles": {
    "payments/payment-flow.svg": {
      "source": "acme/payments",
      "hash": "sha256:..."
    }
  }
}
```

## The lockfile does not control the next run[​](#the-lockfile-does-not-control-the-next-run "Direct link to The lockfile does not control the next run")

The current lockfile is a completed-run receipt and managed-output record. It is not read as a package-manager-style source lock.

Every Federation run:

* Resolves the configured GitHub `ref` again
* Re-indexes the current files for a `file:` source
* Writes a new lockfile after the update succeeds

If `ref` is `main`, a later run can select a newer commit. To make a source repeatable, configure `ref` as an exact commit SHA.

Do not describe the current lockfile as a pin

The commit in `eventcatalog.lock` tells you what the completed run used. It does not force the next run to use that commit.

## Should the lockfile be committed?[​](#should-the-lockfile-be-committed "Direct link to Should the lockfile be committed?")

It is safe to commit `eventcatalog.lock` when you want:

* An auditable record of the last completed federation run
* Managed public-file state shared between environments
* Source revisions visible during code review

Expect a moving branch or edited local source to update the lockfile. Committing it does not by itself make future builds repeatable.

## How the content cache works[​](#how-the-content-cache-works "Direct link to How the content cache works")

Federation stores content under:

```
.eventcatalog-cache/
└── federation/
    └── content/
```

Cache entries are addressed by SHA-256 content hashes. Before reusing an entry, Federation calculates its hash again. A corrupt or mismatched entry is discarded instead of being hydrated.

The cache avoids downloading identical resource files, schemas, specifications, sidecars, and assets on every run.

## Ignore or persist the cache[​](#ignore-or-persist-the-cache "Direct link to Ignore or persist the cache")

Add the cache to `.gitignore`:

```
.eventcatalog-cache/
```

The cache is disposable. You can remove it when you need to reclaim disk space; the next run downloads the required content again.

The current release does not prune old content automatically, so a long-lived cache can grow as source content changes.

Persisting `.eventcatalog-cache` in CI can improve repeat build times, but it is not required for correctness.

## Refresh cached content[​](#refresh-cached-content "Direct link to Refresh cached content")

Use `--no-cache` to disable cache reads for one run:

```
npx eventcatalog federate --no-cache
```

Federation fetches the required content and writes valid content back to the cache. The option refreshes cache entries; it does not permanently disable caching.

## Related guides[​](#related-guides "Direct link to Related guides")

* [Run Federation in CI](/docs/federation/how-to/run-in-ci.md)
* [Generated output reference](/docs/federation/reference/generated-output.md)
* [CLI reference](/docs/federation/reference/cli.md)