Once you've completed installation, you can start to add in entries into your repositories and have the catalog start to pull information in.
An example organization is available to highlight all the possible options that might exist for you. The fictional company Burnt Tomatoes will be used repeatedly throughout these examples.
The GitHub app added provides the interface for adding repositories to the Catalog. To use the Catalog, the app should be installed in a repository in the organization.
To add in every repository for an organisation, install the Catalog app in GitHub to every repository for an organisation. Control of what repositories have access to the Catalog is controlled by GitHub.
Install your GitHub App on your repository
For the Catalog, a source is a repository that hosts the configuration that it will read into the Catalog. Each source can contain any number of configuration files.
By default the Catalog will look in one of the following places in the Source repository:
catalog.json.service-catalog/catalog.json.github/catalog.json
The file contents are validated against this schema.
Each JSON file then maps to one service.
For the Catalog, each Service is an element within your organisation.
The Catalog makes no requirements or definitions about how large or small or Service is or what it is. It could be an application, a team, a group of applications - whatever makes sense for you and your organisation.
Required fields:
name: a name for the service.priority: a number from1to10. Where1is the highest priority,10being the lowest priority.
Optional fields:
type: a string that categorises the service for you in some manner that makes sense.description: a text field that has more space for details about the service. Will be formatted using Markdown.active: a boolean to mark the service as active or not. Default:true.dependencies: an array of strings, where each string is a slug of the service that is a dependency. See below for the slug 👇.meta: an object that allows you to enter any arbitrary detail. See below for more detail 👇.files: an array of strings, where each string is a path relative to the root of the repository that contains more catalog entries. See below for more detail 👇.events: a list of webhooks to listen to on GitHub. Currently only possible values aredeploymentsandreleases. See events for more
When a Service is added to the Catalog it is given a slug using the built-in Django slug function. For example: Database Team becomes database-team.
Slugs must be unique within the Catalog.
The Catalog does not have any requirements or definitions for how Services within the Catalog should provide metadata. This is completely up to the organisation to decide.
It's recommended that the meta contains information that is usefult to people in the organisation who might be unfamiliar with the service, or need to quickly find information in an incident.
Because your organization could be using Slack, Teams, Datadog, Splunk, GitHub, GitHub Enterprise etc., the meta field is deliberately vague and open ended for whatever makes sense for you.
See configuration for information on how to enforce meta.
One repository might have multiple services. To allow this the files array allows one repository to contain multiple services. If files is encountered in a file, the Catalog will pull information from that file.
The files array can be in any file read by the Catalog.