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

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # @backstage/plugin-catalog-backend-module-github
 
+## 0.2.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
+- bef063dc8d: - Make it possible to inject custom user and team transformers when configuring the `GithubOrgEntityProvider`
+- 4c9f7847e4: Updated dependency `msw` to `^0.48.0` while moving it to be a dev dependency.
+- c1784a4980: Replaces in-code uses of `GitHub` with `Github` and deprecates old versions.
+- Updated dependencies
+  - @backstage/backend-common@0.16.0
+  - @backstage/plugin-catalog-backend@1.5.1
+  - @backstage/integration@1.4.0
+  - @backstage/backend-tasks@0.3.7
+  - @backstage/catalog-model@1.1.3
+  - @backstage/types@1.0.1
+  - @backstage/backend-plugin-api@0.1.4
+  - @backstage/plugin-catalog-node@1.2.1
+  - @backstage/catalog-client@1.1.2
+  - @backstage/config@1.0.4
+  - @backstage/errors@1.1.3
+
+## 0.2.0-next.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/backend-common@0.16.0-next.1
+  - @backstage/backend-plugin-api@0.1.4-next.1
+  - @backstage/backend-tasks@0.3.7-next.1
+  - @backstage/plugin-catalog-backend@1.5.1-next.1
+  - @backstage/plugin-catalog-node@1.2.1-next.1
+  - @backstage/catalog-client@1.1.2-next.0
+  - @backstage/catalog-model@1.1.3-next.0
+  - @backstage/config@1.0.4-next.0
+  - @backstage/errors@1.1.3-next.0
+  - @backstage/integration@1.4.0-next.0
+  - @backstage/types@1.0.1-next.0
+
 ## 0.2.0-next.0
 
 ### Minor Changes

package/alpha/package.json

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

package/dist/index.alpha.d.ts

@@ -1,5 +1,5 @@
 /**
- * A Backstage catalog backend module that helps integrate towards GitHub
+ * A Backstage catalog backend module that helps integrate towards Github
  *
  * @packageDocumentation
  */
@@ -14,6 +14,8 @@ 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 { graphql } from '@octokit/graphql';
+import { GroupEntity } from '@backstage/catalog-model';
 import { LocationSpec } from '@backstage/plugin-catalog-backend';
 import { Logger } from 'winston';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
@@ -22,6 +24,21 @@ import { ScmIntegrationRegistry } from '@backstage/integration';
 import { ScmLocationAnalyzer } from '@backstage/plugin-catalog-backend';
 import { TaskRunner } from '@backstage/backend-tasks';
 import { TokenManager } from '@backstage/backend-common';
+import { UserEntity } from '@backstage/catalog-model';
+
+/**
+ * Default transformer for GitHub Team to GroupEntity
+ *
+ * @public
+ */
+export declare const defaultOrganizationTeamTransformer: TeamTransformer;
+
+/**
+ * Default transformer for GitHub users to UserEntity
+ *
+ * @public
+ */
+export declare const defaultUserTransformer: UserTransformer;
 
 /**
  * Extracts repositories out of a GitHub org.
@@ -167,6 +184,7 @@ export declare type GithubMultiOrgConfig = Array<{
  * @public
  */
 export declare class GithubMultiOrgReaderProcessor implements CatalogProcessor {
+    private options;
     private readonly integrations;
     private readonly orgs;
     private readonly logger;
@@ -174,12 +192,16 @@ export declare class GithubMultiOrgReaderProcessor implements CatalogProcessor {
     static fromConfig(config: Config, options: {
         logger: Logger;
         githubCredentialsProvider?: GithubCredentialsProvider;
+        userTransformer?: UserTransformer;
+        teamTransformer?: TeamTransformer;
     }): GithubMultiOrgReaderProcessor;
     constructor(options: {
         integrations: ScmIntegrationRegistry;
         logger: Logger;
         orgs: GithubMultiOrgConfig;
         githubCredentialsProvider?: GithubCredentialsProvider;
+        userTransformer?: UserTransformer;
+        teamTransformer?: TeamTransformer;
     });
     getProcessorName(): string;
     readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
@@ -211,6 +233,8 @@ export declare class GithubOrgEntityProvider implements EntityProvider {
         gitHubConfig: GithubIntegrationConfig;
         logger: Logger;
         githubCredentialsProvider?: GithubCredentialsProvider;
+        userTransformer?: UserTransformer;
+        teamTransformer?: TeamTransformer;
     });
     /** {@inheritdoc @backstage/plugin-catalog-backend#EntityProvider.getProviderName} */
     getProviderName(): string;
@@ -272,6 +296,14 @@ export declare interface GithubOrgEntityProviderOptions {
      * Optionally supply a custom credentials provider, replacing the default one.
      */
     githubCredentialsProvider?: GithubCredentialsProvider;
+    /**
+     * Optionally include a user transformer for transforming from GitHub users to User Entities
+     */
+    userTransformer?: UserTransformer;
+    /**
+     * Optionally include a team transformer for transforming from GitHub teams to Group Entities
+     */
+    teamTransformer?: TeamTransformer;
 }
 
 /**
@@ -301,4 +333,59 @@ export declare class GithubOrgReaderProcessor implements CatalogProcessor {
     private createClient;
 }
 
+/**
+ * Github Team
+ *
+ * @public
+ */
+export declare type GithubTeam = {
+    slug: string;
+    combinedSlug: string;
+    name?: string;
+    description?: string;
+    avatarUrl?: string;
+    editTeamUrl?: string;
+    parentTeam?: GithubTeam;
+    members: GithubUser[];
+};
+
+/**
+ * Github User
+ *
+ * @public
+ */
+export declare type GithubUser = {
+    login: string;
+    bio?: string;
+    avatarUrl?: string;
+    email?: string;
+    name?: string;
+    organizationVerifiedDomainEmails?: string[];
+};
+
+/**
+ * Transformer for GitHub Team to GroupEntity
+ *
+ * @public
+ */
+export declare type TeamTransformer = (item: GithubTeam, ctx: TransformerContext) => Promise<GroupEntity | undefined>;
+
+/**
+ * Context passed to Transformers
+ *
+ * @public
+ */
+export declare interface TransformerContext {
+    client: typeof graphql;
+    query: string;
+    org: string;
+}
+
+/**
+ * Transformer for GitHub users to UserEntity
+ *
+ * @public
+ */
+export declare type UserTransformer = (item: GithubUser, ctx: TransformerContext) => Promise<UserEntity | undefined>;
+
 export { }

package/dist/index.beta.d.ts

@@ -1,5 +1,5 @@
 /**
- * A Backstage catalog backend module that helps integrate towards GitHub
+ * A Backstage catalog backend module that helps integrate towards Github
  *
  * @packageDocumentation
  */
@@ -14,6 +14,8 @@ 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 { graphql } from '@octokit/graphql';
+import { GroupEntity } from '@backstage/catalog-model';
 import { LocationSpec } from '@backstage/plugin-catalog-backend';
 import { Logger } from 'winston';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
@@ -22,6 +24,21 @@ import { ScmIntegrationRegistry } from '@backstage/integration';
 import { ScmLocationAnalyzer } from '@backstage/plugin-catalog-backend';
 import { TaskRunner } from '@backstage/backend-tasks';
 import { TokenManager } from '@backstage/backend-common';
+import { UserEntity } from '@backstage/catalog-model';
+
+/**
+ * Default transformer for GitHub Team to GroupEntity
+ *
+ * @public
+ */
+export declare const defaultOrganizationTeamTransformer: TeamTransformer;
+
+/**
+ * Default transformer for GitHub users to UserEntity
+ *
+ * @public
+ */
+export declare const defaultUserTransformer: UserTransformer;
 
 /**
  * Extracts repositories out of a GitHub org.
@@ -162,6 +179,7 @@ export declare type GithubMultiOrgConfig = Array<{
  * @public
  */
 export declare class GithubMultiOrgReaderProcessor implements CatalogProcessor {
+    private options;
     private readonly integrations;
     private readonly orgs;
     private readonly logger;
@@ -169,12 +187,16 @@ export declare class GithubMultiOrgReaderProcessor implements CatalogProcessor {
     static fromConfig(config: Config, options: {
         logger: Logger;
         githubCredentialsProvider?: GithubCredentialsProvider;
+        userTransformer?: UserTransformer;
+        teamTransformer?: TeamTransformer;
     }): GithubMultiOrgReaderProcessor;
     constructor(options: {
         integrations: ScmIntegrationRegistry;
         logger: Logger;
         orgs: GithubMultiOrgConfig;
         githubCredentialsProvider?: GithubCredentialsProvider;
+        userTransformer?: UserTransformer;
+        teamTransformer?: TeamTransformer;
     });
     getProcessorName(): string;
     readLocation(location: LocationSpec, _optional: boolean, emit: CatalogProcessorEmit): Promise<boolean>;
@@ -206,6 +228,8 @@ export declare class GithubOrgEntityProvider implements EntityProvider {
         gitHubConfig: GithubIntegrationConfig;
         logger: Logger;
         githubCredentialsProvider?: GithubCredentialsProvider;
+        userTransformer?: UserTransformer;
+        teamTransformer?: TeamTransformer;
     });
     /** {@inheritdoc @backstage/plugin-catalog-backend#EntityProvider.getProviderName} */
     getProviderName(): string;
@@ -267,6 +291,14 @@ export declare interface GithubOrgEntityProviderOptions {
      * Optionally supply a custom credentials provider, replacing the default one.
      */
     githubCredentialsProvider?: GithubCredentialsProvider;
+    /**
+     * Optionally include a user transformer for transforming from GitHub users to User Entities
+     */
+    userTransformer?: UserTransformer;
+    /**
+     * Optionally include a team transformer for transforming from GitHub teams to Group Entities
+     */
+    teamTransformer?: TeamTransformer;
 }
 
 /**
@@ -296,4 +328,59 @@ export declare class GithubOrgReaderProcessor implements CatalogProcessor {
     private createClient;
 }
 
+/**
+ * Github Team
+ *
+ * @public
+ */
+export declare type GithubTeam = {
+    slug: string;
+    combinedSlug: string;
+    name?: string;
+    description?: string;
+    avatarUrl?: string;
+    editTeamUrl?: string;
+    parentTeam?: GithubTeam;
+    members: GithubUser[];
+};
+
+/**
+ * Github User
+ *
+ * @public
+ */
+export declare type GithubUser = {
+    login: string;
+    bio?: string;
+    avatarUrl?: string;
+    email?: string;
+    name?: string;
+    organizationVerifiedDomainEmails?: string[];
+};
+
+/**
+ * Transformer for GitHub Team to GroupEntity
+ *
+ * @public
+ */
+export declare type TeamTransformer = (item: GithubTeam, ctx: TransformerContext) => Promise<GroupEntity | undefined>;
+
+/**
+ * Context passed to Transformers
+ *
+ * @public
+ */
+export declare interface TransformerContext {
+    client: typeof graphql;
+    query: string;
+    org: string;
+}
+
+/**
+ * Transformer for GitHub users to UserEntity
+ *
+ * @public
+ */
+export declare type UserTransformer = (item: GithubUser, ctx: TransformerContext) => Promise<UserEntity | undefined>;
+
 export { }