@backstage/plugin-catalog-backend-module-github 0.1.8-next.1 → 0.1.8

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # @backstage/plugin-catalog-backend-module-github
 
+## 0.1.8
+
+### Patch Changes
+
+- 8749df3d02: `GitHubEntityProvider`: Add option to configure schedule via `app-config.yaml` instead of in code.
+
+  Please find how to configure the schedule at the config at
+  https://backstage.io/docs/integrations/github/discovery
+
+- 7022aebf35: Added `GithubLocationAnalyzer`. This can be used to add to the `CatalogBuilder`. When added this will be used by `RepoLocationAnalyzer` to figure out if the given URL that you are trying to import from the /catalog-import page already contains catalog-info.yaml files.
+- 51046b58b0: Use schedule from config at backend module.
+
+  Also, it removes `GithubEntityProviderCatalogModuleOptions`
+  in favor of config-only for the backend module setup
+  like at other similar modules.
+
+- 7edb5909e8: Add missing config schema for the `GitHubEntityProvider`.
+- be9474b103: Replaces in-code uses of `GitHub` by `Github` and deprecates old versions.
+
+  Deprecates
+
+  - `GitHubEntityProvider` replaced by `GithubEntityProvider`
+  - `GitHubLocationAnalyzer` replaced by `GithubLocationAnalyzer`
+  - `GitHubLocationAnalyzerOptions` replaced by `GithubLocationAnalyzerOptions`
+  - `GitHubOrgEntityProvider` replaced by `GithubOrgEntityProvider`
+  - `GitHubOrgEntityProviderOptions` replaced by `GithubOrgEntityProviderOptions`
+
+  Renames
+
+  - `GitHubLocationAnalyzer` to `GithubLocationAnalyzer`
+  - `GitHubLocationAnalyzerOptions` to `GithubLocationAnalyzerOptions`
+
+- a35a27df70: Updated the `moduleId` of the experimental module export.
+- Updated dependencies
+  - @backstage/plugin-catalog-node@1.2.0
+  - @backstage/catalog-model@1.1.2
+  - @backstage/backend-common@0.15.2
+  - @backstage/plugin-catalog-backend@1.5.0
+  - @backstage/backend-tasks@0.3.6
+  - @backstage/backend-plugin-api@0.1.3
+  - @backstage/catalog-client@1.1.1
+  - @backstage/config@1.0.3
+  - @backstage/errors@1.1.2
+  - @backstage/integration@1.3.2
+  - @backstage/types@1.0.0
+
+## 0.1.8-next.2
+
+### Patch Changes
+
+- 7022aebf35: Added `GitHubLocationAnalyzer`. This can be used to add to the `CatalogBuilder`. When added this will be used by `RepoLocationAnalyzer` to figure out if the given URL that you are trying to import from the /catalog-import page already contains catalog-info.yaml files.
+- 7edb5909e8: Add missing config schema for the `GitHubEntityProvider`.
+- Updated dependencies
+  - @backstage/plugin-catalog-node@1.2.0-next.2
+  - @backstage/plugin-catalog-backend@1.5.0-next.2
+  - @backstage/backend-tasks@0.3.6-next.2
+  - @backstage/backend-common@0.15.2-next.2
+  - @backstage/backend-plugin-api@0.1.3-next.2
+  - @backstage/catalog-client@1.1.1-next.2
+  - @backstage/catalog-model@1.1.2-next.2
+  - @backstage/config@1.0.3-next.2
+  - @backstage/errors@1.1.2-next.2
+  - @backstage/integration@1.3.2-next.2
+  - @backstage/types@1.0.0
+
 ## 0.1.8-next.1
 
 ### Patch Changes

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-catalog-backend-module-github",
-  "version": "0.1.8-next.1",
+  "version": "0.1.8",
   "main": "../dist/index.cjs.js",
   "types": "../dist/index.alpha.d.ts"
 }

package/config.d.ts

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+import { TaskScheduleDefinitionConfig } from '@backstage/backend-tasks';
+
 export interface Config {
   catalog?: {
     processors?: {
@@ -45,5 +47,127 @@ 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[];
+              };
+            };
+            /**
+             * (Optional) TaskScheduleDefinition for the refresh.
+             */
+            schedule?: TaskScheduleDefinitionConfig;
+          }
+        | 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[];
+                };
+              };
+              /**
+               * (Optional) TaskScheduleDefinition for the refresh.
+               */
+              schedule?: TaskScheduleDefinitionConfig;
+            }
+          >;
+    };
   };
 }

package/dist/index.alpha.d.ts

@@ -4,19 +4,23 @@
  * @packageDocumentation
  */
 
+import { AnalyzeOptions } from '@backstage/plugin-catalog-backend';
 import { BackendFeature } from '@backstage/backend-plugin-api';
 import { CatalogProcessor } from '@backstage/plugin-catalog-backend';
 import { CatalogProcessorEmit } from '@backstage/plugin-catalog-backend';
 import { Config } from '@backstage/config';
+import { Entity } from '@backstage/catalog-model';
 import { EntityProvider } from '@backstage/plugin-catalog-backend';
 import { EntityProviderConnection } from '@backstage/plugin-catalog-backend';
 import { GithubCredentialsProvider } from '@backstage/integration';
 import { GitHubIntegrationConfig } from '@backstage/integration';
 import { LocationSpec } from '@backstage/plugin-catalog-backend';
 import { Logger } from 'winston';
+import { PluginEndpointDiscovery } from '@backstage/backend-common';
+import { PluginTaskScheduler } from '@backstage/backend-tasks';
 import { ScmIntegrationRegistry } from '@backstage/integration';
+import { ScmLocationAnalyzer } from '@backstage/plugin-catalog-backend';
 import { TaskRunner } from '@backstage/backend-tasks';
-import { TaskScheduleDefinition } from '@backstage/backend-tasks';
 
 /**
  * Extracts repositories out of a GitHub org.
@@ -51,6 +55,23 @@ export declare class GithubDiscoveryProcessor implements CatalogProcessor {
     readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
 }
 
+/**
+ * @public
+ * @deprecated Use {@link GithubEntityProvider} instead.
+ */
+export declare class GitHubEntityProvider implements EntityProvider {
+    private readonly delegate;
+    static fromConfig(config: Config, options: {
+        logger: Logger;
+        schedule?: TaskRunner;
+        scheduler?: PluginTaskScheduler;
+    }): GitHubEntityProvider[];
+    private constructor();
+    connect(connection: EntityProviderConnection): Promise<void>;
+    getProviderName(): string;
+    refresh(logger: Logger): Promise<void>;
+}
+
 /**
  * Discovers catalog files located in [GitHub](https://github.com).
  * The provider will search your GitHub account and register catalog files matching the configured path
@@ -59,7 +80,7 @@ export declare class GithubDiscoveryProcessor implements CatalogProcessor {
  *
  * @public
  */
-export declare class GitHubEntityProvider implements EntityProvider {
+export declare class GithubEntityProvider implements EntityProvider {
     private readonly config;
     private readonly logger;
     private readonly integration;
@@ -68,8 +89,9 @@ export declare class GitHubEntityProvider implements EntityProvider {
     private readonly githubCredentialsProvider;
     static fromConfig(config: Config, options: {
         logger: Logger;
-        schedule: TaskRunner;
-    }): GitHubEntityProvider[];
+        schedule?: TaskRunner;
+        scheduler?: PluginTaskScheduler;
+    }): GithubEntityProvider[];
     private constructor();
     /** {@inheritdoc @backstage/plugin-catalog-backend#EntityProvider.getProviderName} */
     getProviderName(): string;
@@ -84,19 +106,34 @@ export declare class GitHubEntityProvider implements EntityProvider {
 }
 
 /**
- * Registers the GitHubEntityProvider with the catalog processing extension point.
+ * Registers the {@link GithubEntityProvider} with the catalog processing extension point.
  *
  * @alpha
  */
-export declare const githubEntityProviderCatalogModule: (options?: GithubEntityProviderCatalogModuleOptions | undefined) => BackendFeature;
+export declare const githubEntityProviderCatalogModule: (options?: undefined) => BackendFeature;
 
-/**
- * Options for {@link githubEntityProviderCatalogModule}.
- *
- * @alpha
- */
-export declare type GithubEntityProviderCatalogModuleOptions = {
-    schedule?: TaskScheduleDefinition;
+/** @public */
+export declare class GithubLocationAnalyzer implements ScmLocationAnalyzer {
+    private readonly catalogClient;
+    private readonly config;
+    constructor(options: GithubLocationAnalyzerOptions);
+    supports(url: string): boolean;
+    analyze({ url, catalogFilename }: AnalyzeOptions): Promise<{
+        existing: {
+            location: {
+                type: string;
+                target: string;
+            };
+            isRegistered: boolean;
+            entity: Entity;
+        }[];
+    }>;
+}
+
+/** @public */
+export declare type GithubLocationAnalyzerOptions = {
+    config: Config;
+    discovery: PluginEndpointDiscovery;
 };
 
 /**
@@ -145,17 +182,25 @@ export declare class GithubMultiOrgReaderProcessor implements CatalogProcessor {
     private getAllOrgs;
 }
 
+/**
+ * @public
+ * @deprecated Use {@link GithubOrgEntityProvider} instead.
+ */
+export declare class GitHubOrgEntityProvider extends GithubOrgEntityProvider {
+    static fromConfig(config: Config, options: GitHubOrgEntityProviderOptions): GitHubOrgEntityProvider;
+}
+
 /**
  * Ingests org data (users and groups) from GitHub.
  *
  * @public
  */
-export declare class GitHubOrgEntityProvider implements EntityProvider {
+export declare class GithubOrgEntityProvider implements EntityProvider {
     private options;
     private readonly credentialsProvider;
     private connection?;
     private scheduleFn?;
-    static fromConfig(config: Config, options: GitHubOrgEntityProviderOptions): GitHubOrgEntityProvider;
+    static fromConfig(config: Config, options: GithubOrgEntityProviderOptions): GithubOrgEntityProvider;
     constructor(options: {
         id: string;
         orgUrl: string;
@@ -178,11 +223,17 @@ export declare class GitHubOrgEntityProvider implements EntityProvider {
 }
 
 /**
- * Options for {@link GitHubOrgEntityProvider}.
+ * @public
+ * @deprecated Use {@link GithubOrgEntityProviderOptions} instead.
+ */
+export declare type GitHubOrgEntityProviderOptions = GithubOrgEntityProviderOptions;
+
+/**
+ * Options for {@link GithubOrgEntityProvider}.
  *
  * @public
  */
-export declare interface GitHubOrgEntityProviderOptions {
+export declare interface GithubOrgEntityProviderOptions {
     /**
      * A unique, stable identifier for this provider.
      *
@@ -224,7 +275,7 @@ export declare interface GitHubOrgEntityProviderOptions {
  *
  * @remarks
  *
- * Consider using {@link GitHubOrgEntityProvider} instead.
+ * Consider using {@link GithubOrgEntityProvider} instead.
  *
  * @public
  */

package/dist/index.beta.d.ts

@@ -4,19 +4,23 @@
  * @packageDocumentation
  */
 
+import { AnalyzeOptions } from '@backstage/plugin-catalog-backend';
 import { BackendFeature } from '@backstage/backend-plugin-api';
 import { CatalogProcessor } from '@backstage/plugin-catalog-backend';
 import { CatalogProcessorEmit } from '@backstage/plugin-catalog-backend';
 import { Config } from '@backstage/config';
+import { Entity } from '@backstage/catalog-model';
 import { EntityProvider } from '@backstage/plugin-catalog-backend';
 import { EntityProviderConnection } from '@backstage/plugin-catalog-backend';
 import { GithubCredentialsProvider } from '@backstage/integration';
 import { GitHubIntegrationConfig } from '@backstage/integration';
 import { LocationSpec } from '@backstage/plugin-catalog-backend';
 import { Logger } from 'winston';
+import { PluginEndpointDiscovery } from '@backstage/backend-common';
+import { PluginTaskScheduler } from '@backstage/backend-tasks';
 import { ScmIntegrationRegistry } from '@backstage/integration';
+import { ScmLocationAnalyzer } from '@backstage/plugin-catalog-backend';
 import { TaskRunner } from '@backstage/backend-tasks';
-import { TaskScheduleDefinition } from '@backstage/backend-tasks';
 
 /**
  * Extracts repositories out of a GitHub org.
@@ -51,6 +55,23 @@ export declare class GithubDiscoveryProcessor implements CatalogProcessor {
     readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
 }
 
+/**
+ * @public
+ * @deprecated Use {@link GithubEntityProvider} instead.
+ */
+export declare class GitHubEntityProvider implements EntityProvider {
+    private readonly delegate;
+    static fromConfig(config: Config, options: {
+        logger: Logger;
+        schedule?: TaskRunner;
+        scheduler?: PluginTaskScheduler;
+    }): GitHubEntityProvider[];
+    private constructor();
+    connect(connection: EntityProviderConnection): Promise<void>;
+    getProviderName(): string;
+    refresh(logger: Logger): Promise<void>;
+}
+
 /**
  * Discovers catalog files located in [GitHub](https://github.com).
  * The provider will search your GitHub account and register catalog files matching the configured path
@@ -59,7 +80,7 @@ export declare class GithubDiscoveryProcessor implements CatalogProcessor {
  *
  * @public
  */
-export declare class GitHubEntityProvider implements EntityProvider {
+export declare class GithubEntityProvider implements EntityProvider {
     private readonly config;
     private readonly logger;
     private readonly integration;
@@ -68,8 +89,9 @@ export declare class GitHubEntityProvider implements EntityProvider {
     private readonly githubCredentialsProvider;
     static fromConfig(config: Config, options: {
         logger: Logger;
-        schedule: TaskRunner;
-    }): GitHubEntityProvider[];
+        schedule?: TaskRunner;
+        scheduler?: PluginTaskScheduler;
+    }): GithubEntityProvider[];
     private constructor();
     /** {@inheritdoc @backstage/plugin-catalog-backend#EntityProvider.getProviderName} */
     getProviderName(): string;
@@ -85,7 +107,29 @@ export declare class GitHubEntityProvider implements EntityProvider {
 
 /* Excluded from this release type: githubEntityProviderCatalogModule */
 
-/* Excluded from this release type: GithubEntityProviderCatalogModuleOptions */
+/** @public */
+export declare class GithubLocationAnalyzer implements ScmLocationAnalyzer {
+    private readonly catalogClient;
+    private readonly config;
+    constructor(options: GithubLocationAnalyzerOptions);
+    supports(url: string): boolean;
+    analyze({ url, catalogFilename }: AnalyzeOptions): Promise<{
+        existing: {
+            location: {
+                type: string;
+                target: string;
+            };
+            isRegistered: boolean;
+            entity: Entity;
+        }[];
+    }>;
+}
+
+/** @public */
+export declare type GithubLocationAnalyzerOptions = {
+    config: Config;
+    discovery: PluginEndpointDiscovery;
+};
 
 /**
  * The configuration parameters for a multi-org GitHub processor.
@@ -133,17 +177,25 @@ export declare class GithubMultiOrgReaderProcessor implements CatalogProcessor {
     private getAllOrgs;
 }
 
+/**
+ * @public
+ * @deprecated Use {@link GithubOrgEntityProvider} instead.
+ */
+export declare class GitHubOrgEntityProvider extends GithubOrgEntityProvider {
+    static fromConfig(config: Config, options: GitHubOrgEntityProviderOptions): GitHubOrgEntityProvider;
+}
+
 /**
  * Ingests org data (users and groups) from GitHub.
  *
  * @public
  */
-export declare class GitHubOrgEntityProvider implements EntityProvider {
+export declare class GithubOrgEntityProvider implements EntityProvider {
     private options;
     private readonly credentialsProvider;
     private connection?;
     private scheduleFn?;
-    static fromConfig(config: Config, options: GitHubOrgEntityProviderOptions): GitHubOrgEntityProvider;
+    static fromConfig(config: Config, options: GithubOrgEntityProviderOptions): GithubOrgEntityProvider;
     constructor(options: {
         id: string;
         orgUrl: string;
@@ -166,11 +218,17 @@ export declare class GitHubOrgEntityProvider implements EntityProvider {
 }
 
 /**
- * Options for {@link GitHubOrgEntityProvider}.
+ * @public
+ * @deprecated Use {@link GithubOrgEntityProviderOptions} instead.
+ */
+export declare type GitHubOrgEntityProviderOptions = GithubOrgEntityProviderOptions;
+
+/**
+ * Options for {@link GithubOrgEntityProvider}.
  *
  * @public
  */
-export declare interface GitHubOrgEntityProviderOptions {
+export declare interface GithubOrgEntityProviderOptions {
     /**
      * A unique, stable identifier for this provider.
      *
@@ -212,7 +270,7 @@ export declare interface GitHubOrgEntityProviderOptions {
  *
  * @remarks
  *
- * Consider using {@link GitHubOrgEntityProvider} instead.
+ * Consider using {@link GithubOrgEntityProvider} instead.
  *
  * @public
  */