# Installation Copy as Markdown[View as Markdown](/docs/plugins/github/installation.md) *** **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[​](#installation "Direct link to 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](/docs/development/getting-started/installation.md) guide. * Install on existing catalog * Create new catalog with GitHub plugin ``` npm i @eventcatalog/generator-github ``` ``` npx @eventcatalog/create-eventcatalog@latest my-catalog --template github ``` ## Configuration[​](#configuration "Direct link to 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 * Import schemas and assign them to producers and consumers (services) 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 source: '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', }, ] }, ], ]; ``` 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 source: '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[​](#configure-api-keys "Direct link to 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](https://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[​](#white-listing-eventcatalog-domains "Direct link to 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. ### Private repository authentication[​](#private-repository-authentication "Direct link to Private repository authentication") **Added in** `@eventcatalog/generator-github@1.0.0` The GitHub plugin supports authentication for private repositories using GitHub personal access tokens (PAT) or GitHub App installation tokens. You can authenticate in two ways: **Option 1: Environment variable (recommended)** Set the `EVENTCATALOG_GITHUB_TOKEN` environment variable in your `.env` file. .env ``` # EventCatalog license key EVENTCATALOG_LICENSE_KEY_GITHUB=your-license-key # GitHub token for private repository access EVENTCATALOG_GITHUB_TOKEN=ghp_your_token_here ``` **Option 2: Configuration option** Pass the token directly in your configuration file. eventcatalog.config.js ``` generators: [ [ '@eventcatalog/generator-github', { source: 'https://github.com/your-org/private-repo', path: 'schemas', token: process.env.MY_GITHUB_TOKEN, // ... rest of configuration }, ], ]; ``` Create a GitHub token To create a personal access token, visit [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens). For private repositories, you need the `repo` scope. Public repositories For public repositories, authentication is not required. The plugin will work without any token configuration. ### Running the plugin[​](#running-the-plugin "Direct link to Running the plugin") 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[​](#view-your-catalog "Direct link to View your catalog") Run your catalog locally to see the changes ``` npm run dev ``` #### Build your catalog for production[​](#build-your-catalog-for-production "Direct link to Build your catalog for production") ``` npm run build ``` ## Any questions or need help?[​](#any-questions-or-need-help "Direct link to Any questions or need help?") If you get stuck, find an issue or need help, please raise an issue on [GitHub](https://github.com/event-catalog/eventcatalog/issues) or join our [Discord community](https://eventcatalog.dev/discord). You can also find some examples of the plugin in action in our examples repository: [eventcatalog/examples](https://github.com/event-catalog/generators/tree/main/examples/generator-github).