@backstage/plugin-catalog-backend-module-github 0.1.8-next.2 → 0.2.0-next.0

package/CHANGELOG.md

@@ -1,5 +1,97 @@
 # @backstage/plugin-catalog-backend-module-github
 
+## 0.2.0-next.0
+
+### Minor Changes
+
+- 67fe5bc9a9: BREAKING: Support authenticated backends by including a server token for catalog requests. The constructor of `GithubLocationAnalyzer` now requires an instance of `TokenManager` to be supplied:
+
+  ```diff
+  ...
+    builder.addLocationAnalyzers(
+      new GitHubLocationAnalyzer({
+        discovery: env.discovery,
+        config: env.config,
+  +     tokenManager: env.tokenManager,
+      }),
+    );
+  ...
+  ```
+
+- f64d66a45c: Added the ability for the GitHub discovery provider to validate that catalog files exist before emitting them.
+
+  Users can now set the `validateLocationsExist` property to `true` in their GitHub discovery configuration to opt in to this feature.
+  This feature only works with `catalogPath`s that do not contain wildcards.
+
+  When `validateLocationsExist` is set to `true`, the GitHub discovery provider will retrieve the object from the
+  repository at the provided `catalogPath`.
+  If this file exists and is non-empty, then it will be emitted as a location for further processing.
+  If this file does not exist or is empty, then it will not be emitted.
+  Not emitting locations that do not exist allows for far fewer calls to the GitHub API to validate locations that do not exist.
+
+### Patch Changes
+
+- 67fe5bc9a9: Properly derive Github credentials when making requests in `GithubLocationAnalyzer` to support Github App authentication
+- c1784a4980: Replaces in-code uses of `GitHub` with `Github` and deprecates old versions.
+- Updated dependencies
+  - @backstage/backend-common@0.16.0-next.0
+  - @backstage/plugin-catalog-backend@1.5.1-next.0
+  - @backstage/integration@1.4.0-next.0
+  - @backstage/backend-tasks@0.3.7-next.0
+  - @backstage/catalog-model@1.1.3-next.0
+  - @backstage/types@1.0.1-next.0
+  - @backstage/backend-plugin-api@0.1.4-next.0
+  - @backstage/plugin-catalog-node@1.2.1-next.0
+  - @backstage/catalog-client@1.1.2-next.0
+  - @backstage/config@1.0.4-next.0
+  - @backstage/errors@1.1.3-next.0
+
+## 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

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-catalog-backend-module-github",
-  "version": "0.1.8-next.2",
+  "version": "0.2.0-next.0",
   "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?: {
@@ -48,7 +50,7 @@ export interface Config {
 
     providers?: {
       /**
-       * GitHubEntityProvider configuration
+       * GithubEntityProvider configuration
        *
        * Uses "default" as default id for the single config variant.
        */
@@ -103,6 +105,10 @@ export interface Config {
                 exclude?: string[];
               };
             };
+            /**
+             * (Optional) TaskScheduleDefinition for the refresh.
+             */
+            schedule?: TaskScheduleDefinitionConfig;
           }
         | Record<
             string,
@@ -156,6 +162,10 @@ export interface Config {
                   exclude?: string[];
                 };
               };
+              /**
+               * (Optional) TaskScheduleDefinition for the refresh.
+               */
+              schedule?: TaskScheduleDefinitionConfig;
             }
           >;
     };

package/dist/index.alpha.d.ts

@@ -13,14 +13,15 @@ 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 { 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';
+import { TokenManager } from '@backstage/backend-common';
 
 /**
  * Extracts repositories out of a GitHub org.
@@ -55,6 +56,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
@@ -63,7 +81,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;
@@ -72,8 +90,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;
@@ -88,26 +107,19 @@ 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;
-
-/**
- * Options for {@link githubEntityProviderCatalogModule}.
- *
- * @alpha
- */
-export declare type GithubEntityProviderCatalogModuleOptions = {
-    schedule?: TaskScheduleDefinition;
-};
+export declare const githubEntityProviderCatalogModule: (options?: undefined) => BackendFeature;
 
 /** @public */
-export declare class GitHubLocationAnalyzer implements ScmLocationAnalyzer {
+export declare class GithubLocationAnalyzer implements ScmLocationAnalyzer {
     private readonly catalogClient;
-    private readonly config;
-    constructor(options: GitHubLocationAnalyzerOptions);
+    private readonly githubCredentialsProvider;
+    private readonly integrations;
+    private readonly tokenManager;
+    constructor(options: GithubLocationAnalyzerOptions);
     supports(url: string): boolean;
     analyze({ url, catalogFilename }: AnalyzeOptions): Promise<{
         existing: {
@@ -122,9 +134,10 @@ export declare class GitHubLocationAnalyzer implements ScmLocationAnalyzer {
 }
 
 /** @public */
-export declare type GitHubLocationAnalyzerOptions = {
+export declare type GithubLocationAnalyzerOptions = {
     config: Config;
     discovery: PluginEndpointDiscovery;
+    tokenManager: TokenManager;
 };
 
 /**
@@ -173,21 +186,29 @@ 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;
-        gitHubConfig: GitHubIntegrationConfig;
+        gitHubConfig: GithubIntegrationConfig;
         logger: Logger;
         githubCredentialsProvider?: GithubCredentialsProvider;
     });
@@ -206,11 +227,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.
      *
@@ -252,7 +279,7 @@ export declare interface GitHubOrgEntityProviderOptions {
  *
  * @remarks
  *
- * Consider using {@link GitHubOrgEntityProvider} instead.
+ * Consider using {@link GithubOrgEntityProvider} instead.
  *
  * @public
  */

package/dist/index.beta.d.ts

@@ -13,14 +13,15 @@ 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 { 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';
+import { TokenManager } from '@backstage/backend-common';
 
 /**
  * Extracts repositories out of a GitHub org.
@@ -55,6 +56,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
@@ -63,7 +81,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;
@@ -72,8 +90,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;
@@ -89,13 +108,13 @@ 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 {
+export declare class GithubLocationAnalyzer implements ScmLocationAnalyzer {
     private readonly catalogClient;
-    private readonly config;
-    constructor(options: GitHubLocationAnalyzerOptions);
+    private readonly githubCredentialsProvider;
+    private readonly integrations;
+    private readonly tokenManager;
+    constructor(options: GithubLocationAnalyzerOptions);
     supports(url: string): boolean;
     analyze({ url, catalogFilename }: AnalyzeOptions): Promise<{
         existing: {
@@ -110,9 +129,10 @@ export declare class GitHubLocationAnalyzer implements ScmLocationAnalyzer {
 }
 
 /** @public */
-export declare type GitHubLocationAnalyzerOptions = {
+export declare type GithubLocationAnalyzerOptions = {
     config: Config;
     discovery: PluginEndpointDiscovery;
+    tokenManager: TokenManager;
 };
 
 /**
@@ -161,21 +181,29 @@ 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;
-        gitHubConfig: GitHubIntegrationConfig;
+        gitHubConfig: GithubIntegrationConfig;
         logger: Logger;
         githubCredentialsProvider?: GithubCredentialsProvider;
     });
@@ -194,11 +222,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.
      *
@@ -240,7 +274,7 @@ export declare interface GitHubOrgEntityProviderOptions {
  *
  * @remarks
  *
- * Consider using {@link GitHubOrgEntityProvider} instead.
+ * Consider using {@link GithubOrgEntityProvider} instead.
  *
  * @public
  */