Plugin Configuration

Overview

The EventCatalog GitHub plugin is configured in the eventcatalog.config.js file inside the generators array.

Required Configuration Options

Option	Type	Required	Example	Description
source	string	Yes	https://github.com/event-catalog/eventcatalog.git	The HTTP or SSH URL of the GitHub repository.
path	string	Yes	examples/default	The path to the directory in the repository that contains the schemas.

Optional Configuration Options

Messages

You can assign schemas to messages (events, commands, or commands) in EventCatalog.

Documentation

Remember the GitHub plugin will keep your schemas in sync with your messages. Any documentation (markdown) added to your messages will be persisted between imports and versions.

Option	Type	Required	Default	Description
messages	object	-	-	List of messages to assign the schemas to.
messages.id	string	Yes	-	EventCatalog ID for the message.
messages.name	string	No	-	Friendly name of the message, if not provided the message id will be used.
messages.version	string	No	-	Version of the message, recommended you set this to the version of the message in the repository, Defaults to 1.
messages.schemaPath	string	Yes	-	The path to your schema file in the repository, relative to the path configured in the path option. For example if path is examples/default and your schemaPath is /schemas/order-placed.avro, the path used will be examples/default/schemas/order-placed.avro.
messages.type	string	Yes	-	Type of the message (event, command, or query).

See an example configuration - Assign schemas to messages

In this example we assign schemas to messages.

// ...rest of eventcatalog.config.js file
generators: [
  [
    '@eventcatalog/generator-github',
    {
      source: 'https://github.com/event-catalog/eventcatalog.git',
      path: 'examples/default',
      messages: [
        {
          id: 'order-placed',
          name: 'Order Placed',
          version: '1',
          schemaPath: 'domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.avro',
          type: 'event',
        }, 
        {
          id: 'update-order',
          name: 'Update Order',
          version: '1',
          schemaPath: 'domains/Orders/services/InventoryService/commands/UpdateOrder/schema.avro',
          type: 'command',
        }, 
      ]
    }
  ]
]

Services

You can assign your schemas to your producers and consumers (services).

Documentation

Remember the GitHub plugin will keep your schemas in sync with your services. Any documentation (markdown) added to your services will be persisted between imports and versions.

Option	Type	Default	Required	Description
services	object	-	Yes	List of producers/consumers (services) to assign the schemas to.
services.id	string	-	Yes	EventCatalog ID for the service.
services.sends	Message[]	-	No	Configuration to assign schemas to a producer. The schemas and topic defined here will be assigned to the producer.
services.receives	Message[]	-	No	Configuration to assign schemas to a consumer. The schemas and topic defined here will be assigned to the consumer.

See an example configuration - Assign schemas to producers and consumers

In this example we assign schemas to producers and consumers (services).

// ...rest of eventcatalog.config.js file
generators: [
  [
    '@eventcatalog/generator-github',
    {
      source: 'https://github.com/event-catalog/eventcatalog.git',
      path: 'examples/default',
      services: [
        {
          id: 'Orders Service',
          // The order service sends these messages...
          sends: [
            {
              id: 'order-placed', 
              name: 'Order Placed',
              version: '1',
              schemaPath: 'domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.avro',
              type: 'event',
            }
          ],
          // The order service receives these messages...
          receives: [{
            {
              id: 'place-order', 
              version: '1',
              schemaPath: 'domains/Orders/services/InventoryService/commands/UpdateOrder/schema.avro',
              type: 'command',
            }
          }]
        }
      ]
    }
  ]
]

Domains

You can define and assign domains to your services.

Option	Type	Default	Description
domain.id	string	-	EventCatalog ID for the domain (e.g orders-domain).
domain.name	string	-	Name of the domain (e.g Orders Domain).
domain.version	string	-	Version of the domain (e.g 1.0.0).

See an example configuration - Assign a domain to a service

In this example we assign a domain to a service.

// ...rest of eventcatalog.config.js file
generators: [
  [
    '@eventcatalog/generator-github',
    { 
      source: 'https://github.com/event-catalog/eventcatalog.git',
      path: 'examples/default',
      services: [
        {
          id: 'Orders Service',
          version: '1.0.0',
          sends: [
            {
              id: 'order-placed',
              name: 'Order Placed',
              version: '1',
              schemaPath: 'domains/Orders/services/InventoryService/events/InventoryAdjusted/schema.avro',
              type: 'event',
            }
          ],
          receives: [
            {
              id: 'place-order',
              version: '1',
              schemaPath: 'domains/Orders/services/InventoryService/commands/UpdateOrder/schema.avro',
              type: 'command',
            }
          ]
        }
      ],
      // The list of services are assigned to this domain
      domain: {
        id: 'orders-domain',
        name: 'Orders Domain',
        version: '1.0.0',
      }
    }
  ]
]

Need help?

If you have questions or need help, you can join our Discord community or refer to the Github Plugin examples on GitHub.