diff --git a/.changeset/purple-masks-travel.md b/.changeset/purple-masks-travel.md new file mode 100644 index 0000000000..65d0a5fe9b --- /dev/null +++ b/.changeset/purple-masks-travel.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend-module-github': patch +--- + +Add missing config schema for the `GitHubEntityProvider`. diff --git a/docs/integrations/github/discovery.md b/docs/integrations/github/discovery.md index 6acb87ac37..9b60b41682 100644 --- a/docs/integrations/github/discovery.md +++ b/docs/integrations/github/discovery.md @@ -12,7 +12,7 @@ The GitHub integration has a discovery provider for discovering catalog entities within a GitHub organization. The provider will crawl the GitHub organization and register entities matching the configured path. This can be useful as an alternative to static locations or manually adding things to the -catalog. This is the prefered method for ingesting entities into the catalog. +catalog. This is the preferred method for ingesting entities into the catalog. ## Installation @@ -55,7 +55,7 @@ And then add the entity provider to your catalog builder: To use the discovery provider, you'll need a GitHub integration [set up](locations.md) with either a [Personal Access Token](../../getting-started/configuration.md#setting-up-a-github-integration) or [GitHub Apps](./github-apps.md). -Then you can add a github config to the catalog providers configuration: +Then you can add a `github` config to the catalog providers configuration: ```yaml catalog: @@ -121,10 +121,10 @@ This provider supports multiple organizations via unique provider IDs. In the example above, a repository with the `backstage-include` topic would still be excluded if it were also carrying the `experiments` topic. - **include** _(optional)_: - An array of strings used to filter in results based on their associated Github topics. + An array of strings used to filter in results based on their associated GitHub topics. If configured, only repositories with one (or more) topic(s) present in the inclusion filter will be ingested - **exclude** _(optional)_: - An array of strings used to filter out results based on their associated Github topics. + An array of strings used to filter out results based on their associated GitHub topics. If configured, all repositories _except_ those with one (or more) topics(s) present in the exclusion filter will be ingested. - **organization**: Name of your organization account/workspace. diff --git a/plugins/catalog-backend-module-github/config.d.ts b/plugins/catalog-backend-module-github/config.d.ts index a1702799c2..1dcd49ea4e 100644 --- a/plugins/catalog-backend-module-github/config.d.ts +++ b/plugins/catalog-backend-module-github/config.d.ts @@ -45,5 +45,119 @@ export interface Config { }>; }; }; + + providers?: { + /** + * GitHubEntityProvider configuration + * + * Uses "default" as default id for the single config variant. + */ + github?: + | { + /** + * (Optional) The hostname of your GitHub Enterprise instance. + * Default: `github.com`. + */ + host?: string; + /** + * (Required) Name of your organization account/workspace. + */ + organization: string; + /** + * (Optional) Path where to look for `catalog-info.yaml` files. + * You can use wildcards - `*` or `**` - to search the path and/or the filename + * Default: `/catalog-info.yaml`. + */ + catalogPath?: string; + /** + * (Optional) Filter configuration. + */ + filters?: { + /** + * (Optional) String used to filter results based on the branch name. + */ + branch?: string; + /** + * (Optional) Regular expression used to filter results based on the repository name. + */ + repository?: string; + /** + * (Optional) GitHub topic-based filters. + */ + topic?: { + /** + * (Optional) An array of strings used to filter in results based on their associated GitHub topics. + * If configured, only repositories with one (or more) topic(s) present in the inclusion + * filter will be ingested. + * + * If `include` and `exclude` are used, `exclude` has higher priority. + */ + include?: string[]; + /** + * (Optional) An array of strings used to filter out results based on their associated GitHub topics. + * If configured, all repositories _except_ those with one (or more) topics(s) present in + * the exclusion filter will be ingested. + * + * If `include` and `exclude` are used, `exclude` has higher priority. + */ + exclude?: string[]; + }; + }; + } + | Record< + string, + { + /** + * (Optional) The hostname of your GitHub Enterprise instance. + * Default: `github.com`. + */ + host?: string; + /** + * (Required) Name of your organization account/workspace. + */ + organization: string; + /** + * (Optional) Path where to look for `catalog-info.yaml` files. + * You can use wildcards - `*` or `**` - to search the path and/or the filename + * Default: `/catalog-info.yaml`. + */ + catalogPath?: string; + /** + * (Optional) Filter configuration. + */ + filters?: { + /** + * (Optional) String used to filter results based on the branch name. + */ + branch?: string; + /** + * (Optional) Regular expression used to filter results based on the repository name. + */ + repository?: string; + /** + * (Optional) GitHub topic-based filters. + */ + topic?: { + /** + * (Optional) An array of strings used to filter in results based on their associated GitHub topics. + * If configured, only repositories with one (or more) topic(s) present in the inclusion + * filter will be ingested. + * + * If `include` and `exclude` are used, `exclude` has higher priority. + */ + include?: string[]; + /** + * (Optional) An array of strings used to filter out results based on their associated GitHub topics. + * If configured, all repositories _except_ those with one (or more) topics(s) present in + * the exclusion filter will be ingested. + * + * If `include` and `exclude` are used, `exclude` has higher priority. + */ + exclude?: string[]; + }; + }; + } + >; + }; }; }