Using GitHub as a schema registry with EventCatalog
Event-driven architecture (EDA) practitioners often rely on schema registries to manage their event schemas. Popular solutions include the Confluent Schema Registry, Apicurio Registry, and cloud-based options like AWS Glue Registry, Azure Schema Registry, and Amazon EventBridge Schema Registry. These tools offer ready-to-use solutions for versioning, managing, and retrieving schemas at runtime.
However, through conversations with EventCatalog users, we discovered that many teams are also leveraging GitHub as a schema registry. GitHub’s built-in version control, collaborative feedback features, and ability to serve as a single source of truth make it a practical choice for managing schemas.
Despite their utility, traditional schema registries often fall short in one key area: context. While they store the schema data (like JSON, Avro, or Protobuf), they lack insights into how schemas are used, who produces or consumes them, and which teams are responsible for maintaining them.
EventCatalog aims to bridge this gap by enhancing the discoverability of event-driven architecture. We believe that by running EventCatalog alongside your existing schema registries, you can unlock greater value from your schemas and your organization.
If you're using GitHub as your schema registry, this blog post will guide you through syncing your schemas with your documentation, associating them with producers and consumers, and extracting more meaningful insights from your JSON, Avro, or Protobuf schemas.
Using GitHub as a schema registry
There is no standardized approach for using GitHub as a schema registry—no universal folder structure or patterns. Typically, teams maintain a repository that houses their schemas. In this blog post, we will use an example schema registry called the FlowMart Schema Registry (see on GitHub).
As shown, the repository organizes schemas into folders, each representing a specific context. Within these folders are the schemas themselves, which naturally benefit from version control through Git. Teams often update schemas by creating a new version file while deprecating older ones as needed.
However, despite being versioned, these schemas lack contextual information. While it’s possible to add README files to explain their usage, this manual approach doesn’t offer a clear, visual representation of how schemas are applied or who is responsible for them.
That’s where EventCatalog comes in. With the EventCatalog GitHub integration, you can seamlessly sync your schemas with your documentation. This integration not only keeps your schemas up to date from external sources but also enables you to add context, visualize your architecture, and better understand how your schemas are used across your applications.
By leveraging EventCatalog, your teams can gain a clearer, more structured understanding of how schemas support your business processes.
EventCatalog generated from schemas in GitHub repositoryIntegrating GitHub with EventCatalog
EventCatalog supports integration with any broker or schema registry, providing flexibility to users regardless of their existing setup. We already offer integrations with popular tools such as Confluent Schema Registry, Backstage, OpenAPI, and AsyncAPI. Now, we’ve introduced a new integration with GitHub.
If you want to explore examples right away, check out our GitHub repository: EventCatalog GitHub Generators.
Step 1: Create a New Catalog
If you don’t already have a catalog, create one using the following command:
npx @eventcatalog/create-eventcatalog@latest my-catalog
Step 2: Install the GitHub Plugin
Once your catalog is set up, you need to integrate it with your GitHub repository. For this example, we’ll use the FlowMart Schema Registry (see on GitHub). First, install the GitHub generator plugin:
npm i @eventcatalog/generator-github
This command installs the necessary components to pull schemas from the remote repository.
Step 3: Configure the Plugin
To link your catalog with GitHub, update the eventcatalog.config.js file with the following configuration:
// rest of conf file
generators: [
'@eventcatalog/generator-github',
{
// The URL of your GitHub repository
repository: 'https://github.com/event-catalog/eventcatalog',
// The branch to pull schemas from (default: main)
branch: 'main',
// The root path to your schemas
path: 'some-folder/schemas',
// The producers and consumers (services) to assign schemas to (optional)
services: [
{
id: 'Orders Service',
version: '1.0.0',
// the messages this service sends
sends: [{
id: 'place-order',
version: '2.1',
// The path to the schema file (relative to the root path, some-folder/schemas/place-order.avro)
schemaPath: 'place-order.avro',
// The type of message, can be 'command', 'event' or 'query'
type: 'command',
}],
// the messages this service receives
receives: [{
id: 'order-shipped',
version: '1.0',
// The path to the schema file (relative to the root path, some-folder/schemas/order-shipped.avro)
schemaPath: 'order-shipped.avro',
// The type of message, can be 'command', 'event' or 'query'
type: 'event',
}],
},
{
id: 'Inventory Service',
version: '1.0.0',
// the messages this service sends
sends: [{
id: 'inventory-updated',
version: '1.0',
// The path to the schema file (relative to the root path, some-folder/schemas/inventory-updated.avro)
schemaPath: 'inventory-updated.avro',
// The type of message, can be 'command', 'event' or 'query'
type: 'event',
}],
// the messages this service receives
receives: [{
id: 'order-placed',
version: '1.0',
// The path to the schema file (relative to the root path, some-folder/schemas/order-placed.avro)
schemaPath: 'order-placed.avro',
// The type of message, can be 'command', 'event' or 'query'
type: 'event',
}],
},
],
// We assign the services to a domain "Retail Domain" (optional)
domain: {
id: 'retail-domain',
name: 'Retail Domain',
version: '1.0.0',
}
},
]
This configuration creates two services, Orders Service and Inventory Service, which both send and receive messages (commands and events). The services are grouped under the Retail Domain.
Step 4: Generate the Catalog
After configuring the plugin, generate the catalog using:
npm run generate
This command pulls your schemas from GitHub, assigns them to the relevant services, and organizes your architecture. If a service or message doesn’t exist in EventCatalog, it will be created, and on future imports, only the schema will be updated, preserving your existing documentation.
Step 5: Run the Catalog Locally
To view your catalog locally, start the development server:
npm run dev
Visit localhost:3000 to see your generated catalog, complete with integrated schemas and documentation.
By combining GitHub with EventCatalog, you can keep your schemas synchronized while also documenting producers, consumers, and service relationships—all within a unified, visual interface.
To get started you can read the GitHub integration documentation.
Unlocking the Full Potential of Your Schemas with EventCatalog
Once you have imported and synced your schemas, EventCatalog offers a range of features designed to enhance their usability and discoverability. Here are some of the key features that can add value to your schema management process:
1. EventCatalog Visualizer
The EventCatalog Visualizer allows you to see the relationships between your producers and consumers, making it easy to understand how messages flow through your architecture. You can simulate message exchanges between services and access detailed documentation and schema information by right-clicking on any node. This visual insight helps you map interactions in your event-driven system effectively.
2. Embed Schemas Directly in Documentation
Since it’s your documentation, you have the flexibility to include any content you want. EventCatalog makes it even better by providing Schema and SchemaViewer components, allowing you to embed schemas directly into your documentation. This integration ensures that your documentation remains accurate, comprehensive, and context-rich, while also being visually informative.
3. Quick Schema Downloads
Users can easily download schemas directly from the EventCatalog UI. This feature is especially useful for teams needing quick access to schema details without navigating through complex repositories. It saves time and ensures that your teams always have the latest schema versions on hand.
4. Conversational Insights with EventCatalog Chat
EventCatalog Chat leverages LLMs (Large Language Models) to let you interact with your architecture. You can query your producers, consumers, and schemas conversationally, helping you find insights faster than manually sifting through GitHub repositories. This feature is ideal for quickly understanding how different parts of your architecture are interconnected. You can also use EventCatalog MCP server to query your schemas directly in your code editors.
5. Assign Ownership for Better Accountability
Assigning ownership to producers, consumers, and schemas within EventCatalog makes it easy to track who is responsible for specific parts of your architecture. This feature helps you quickly identify the right team or person when you need to update a schema or troubleshoot an issue. By clearly defining ownership, you reduce the risk of orphaned schemas and ensure accountability.
By leveraging these features, EventCatalog transforms your schema management from a static, isolated process into an interactive and insightful experience. Whether you need visualization, quick downloads, conversational insights, or clear ownership mapping, EventCatalog enhances how you manage and understand your event-driven architecture.
Summary
Event-driven architectures often rely on schema registries like Confluent, Apicurio, AWS Glue, and Azure Schema Registry to manage event schemas. However, these registries typically lack context, making it difficult to understand how schemas are used, who owns them, and how they fit into the broader architecture. Many teams also use GitHub as a schema registry due to its version control and collaboration features, but this approach also lacks visualization and contextual insights.
EventCatalog addresses these challenges by integrating with both traditional registries and GitHub, enhancing schema discoverability and usability. With the GitHub integration, you can automatically sync schemas, visualize producer-consumer relationships, embed schemas in documentation, assign ownership, and use conversational insights with EventCatalog Chat. This holistic approach not only centralizes schema management but also makes it intuitive and insightful for development teams.
If you want to learn more about how to use EventCatalog with GitHub you can read the GitHub integration documentation.
We are coming to Current London 2025!
We are coming to https://current.confluent.io/london in May! If you are coming to the conference, we would love to hang out, just reach out!
If you have any questions or want to join our community of over 1100 people exploring EventCatalog and event-driven architecture feel free to join us!