Installation

License: Dual-license

The GitHub plugin is used to pull and sync your schemas from your GitHub repository to EventCatalog, these can be public or private repositories.

You can map your schemas from your GitHub repository to commands, events and queries in your catalog, and assign these to services (producers and consumers) and domains.

Installation

Run the command below to install the EventCatalog GitHub plugin.

"Don't have an EventCatalog project yet?"

If you don't have an EventCatalog project yet, you can follow the instructions in the Getting Started guide.

Install on existing catalog

npm i @eventcatalog/generator-github

Create new catalog with GitHub plugin

npx @eventcatalog/create-eventcatalog@latest my-catalog --template github

Configuration

To use the plugin you need to configure it in your eventcatalog.config.js file.

Add the plugin to the generators array.

Assign schemas to commands, events and queries

In this example we assign schemas to commands, events and queries in our catalog.

We don't create any producers or consumers in this example.

"Why would I import schemas without assigning them to producers or consumers?"

You may just want to import the schemas into EventCatalog (events, queries, commands) without assigning them to producers or consumers. You can assign them later to producers and consumers yourself in EventCatalog.

eventcatalog.config.js

// ...
generators: [
  // 1. Import all schemas from a Confluent Schema Registry
  [
    '@eventcatalog/generator-github',
    {
      // The HTTP or SSH 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',
      messages: [
        {
          // the id of the message, needed for eventcatalog
          id: 'place-order',
          // Optional name for your message (if not provided, the id will be used)
          name: 'Place Order',
          // Optional version for your message (if not provided, default version of 1 will be used)
          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',
        },
        // just required fields, defaulting version and name
        {
          id: 'order-shipped',
          // The path to the schema file (relative to the root path, some-folder/schemas/order-shipped.avro)
          schemaPath: 'order-shipped.avro',
          type: 'event',
        },
      ]
    },
  ],
];

Import schemas and assign them to producers and consumers (services)

In this example we import schemas from a GitHub repository, and assign them to producers and consumers (services). We also create a domain and assign our services to it.

Adding documentation to your schemas

This plugin will import and keep your schemas in sync with your producers and consumers.

You can still use EventCatalog to document your schemas, services and domains using markdown. The markdown is persisted between imports. This let's you add semantic meaning to your schemas, and document them for your teams, whilst keeping your schemas in sync with your producers and consumers.

In this example we:

• Create two services (producers and consumers)
  • Orders Service
    • Sends place-order command
    • Receives order-shipped event
  • Inventory Service
    • Sends inventory-updated event
    • Receives order-placed event
• Create a domain Retail Domain
  • Assign the services to the domain

eventcatalog.config.js

// ...
 [
  '@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',
        }
      },
    ]

Configure API keys

The EventCatalog GitHub plugin requires API keys in your environment variables.

1. A license key for the GitHub plugin (14 days trial, at EventCatalog Cloud)

Create a .env file in the root, and add your keys to the project.

.env

# EventCatalog license key
EVENTCATALOG_LICENSE_KEY_GITHUB=your-license-key

White listing EventCatalog domains

If you are behind a firewall you will need to white list the domain https://api.eventcatalog.cloud in your firewall. This is because the plugin needs to verify your license key.

Running the plugin

Authentication to private repositories

The machine running the plugin needs to have access to git in the terminal and have access to the repository.

If you are running the plugin in a CI/CD pipeline you can configure the machine to have access to your repository.

Run the plugin to import your schemas into EventCatalog.

This command will run the generators in your eventcatalog.config.js file.

npm run generate

View your catalog

Run your catalog locally to see the changes

npm run dev

Build your catalog for production

npm run build

Any questions or need help?

If you get stuck, find an issue or need help, please raise an issue on GitHub or join our Discord community.

You can also find some examples of the plugin in action in our examples repository: eventcatalog/examples.