catalog-backend-module-github-org: fix default namespace for groups

.changeset/red-mangos-fly.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend-module-github-org': patch
+---
+
+Fixed an issue where the `catalog-backend-module-github-org` would not correctly create groups using `default` as namespace in case a single organization was configured.

.changeset/wild-cats-hug.md

@@ -0,0 +1,7 @@
+---
+'@backstage/plugin-catalog-backend-module-github': patch
+---
+
+Added `alwaysUseDefaultNamespace` option to `GithubMultiOrgEntityProvider`.
+
+If set to true, the provider will use `default` as the namespace for all group entities. Groups with the same name across different orgs will be considered the same group.

docs/backend-system/building-backends/08-migrating.md

@@ -452,7 +452,7 @@ catalog:
         /* highlight-add-end */
 ```
 
-To migrate `GithubMultiOrgEntityProvider` and `GithubOrgEntityProvider` to the new backend system, add a reference to `@backstage/plugin-catalog-backend-module-github-org`.
+To migrate `GithubMultiOrgEntityProvider` or `GithubOrgEntityProvider` to the new backend system, add a reference to `@backstage/plugin-catalog-backend-module-github-org`.
 
 ```ts title="packages/backend/src/index.ts"
 backend.add(import('@backstage/plugin-catalog-backend/alpha'));
@@ -461,20 +461,79 @@ backend.add(import('@backstage/plugin-catalog-backend-module-github-org'));
 /* highlight-add-end */
 ```
 
-If you were providing a `schedule` in code, this now needs to be set via configuration.
-All other Github configuration in `app-config.yaml` remains the same.
+##### GithubOrgEntityProvider
+
+If you were using `GithubOrgEntityProvider` you might have been configured in code like this:
+
+```ts title="packages/backend/src/plugins/catalog.ts"
+// The org URL below needs to match a configured integrations.github entry
+// specified in your app-config.
+builder.addEntityProvider(
+  GithubOrgEntityProvider.fromConfig(env.config, {
+    id: 'production',
+    orgUrl: 'https://github.com/backstage',
+    logger: env.logger,
+    schedule: env.scheduler.createScheduledTaskRunner({
+      frequency: { minutes: 60 },
+      timeout: { minutes: 15 },
+    }),
+  }),
+);
+```
+
+This now needs to be set via configuration. The options defined above are now set in `app-config.yaml` instead as shown below:
 
 ```yaml title="app-config.yaml"
 catalog:
+  /* highlight-add-start */
   providers:
     githubOrg:
-      yourProviderId:
-        # ...
-        /* highlight-add-start */
+      - id: production
+        githubUrl: 'https://github.com',
+        orgs: ['backstage']
         schedule:
           frequency: PT30M
-          timeout: PT3M
-        /* highlight-add-end */
+          timeout: PT15M
+          /* highlight-add-end */
+```
+
+##### GithubMultiOrgEntityProvider
+
+If you were using `GithubMultiOrgEntityProvider` you might have been configured in code like this:
+
+```ts title="packages/backend/src/plugins/catalog.ts"
+// The GitHub URL below needs to match a configured integrations.github entry
+// specified in your app-config.
+builder.addEntityProvider(
+  GithubMultiOrgEntityProvider.fromConfig(env.config, {
+    id: 'production',
+    githubUrl: 'https://github.com',
+    // Set the following to list the GitHub orgs you wish to ingest from. You can
+    // also omit this option to ingest all orgs accessible by your GitHub integration
+    orgs: ['org-a', 'org-b'],
+    logger: env.logger,
+    schedule: env.scheduler.createScheduledTaskRunner({
+      frequency: { minutes: 60 },
+      timeout: { minutes: 15 },
+    }),
+  }),
+);
+```
+
+This now needs to be set via configuration. The options defined above are now set in `app-config.yaml` instead as shown below:
+
+```yaml title="app-config.yaml"
+catalog:
+  /* highlight-add-start */
+  providers:
+    githubOrg:
+      - id: production
+        githubUrl: 'https://github.com',
+        orgs: ['org-a', 'org-b'],
+        schedule:
+          frequency: PT30M
+          timeout: PT15M
+          /* highlight-add-end */
 ```
 
 If you were providing transformers, these can be configured by extending `githubOrgEntityProviderTransformsExtensionPoint`

docs/integrations/github/org.md

@@ -45,7 +45,7 @@ Next add the basic configuration to `app-config.yaml`
 catalog:
   providers:
     githubOrg:
-      id: github
+      id: production
       githubUrl: https://github.com
       orgs: ['organization-1', 'organization-2', 'organization-3']
       schedule:

plugins/catalog-backend-module-github-org/src/GithubOrgEntityCleanerProvider.ts

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2024 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { LoggerService } from '@backstage/backend-plugin-api';
+import {
+  EntityProvider,
+  EntityProviderConnection,
+} from '@backstage/plugin-catalog-node';
+
+export class GithubOrgEntityCleanerProvider implements EntityProvider {
+  logger: LoggerService;
+  constructor(private readonly options: { id: string; logger: LoggerService }) {
+    this.logger = options.logger.child({ target: this.getProviderName() });
+  }
+
+  getProviderName() {
+    return `GithubOrgEntityProvider:${this.options.id}`;
+  }
+  async connect(connection: EntityProviderConnection) {
+    // Clean up any existing entities
+    connection
+      .applyMutation({
+        type: 'full',
+        entities: [],
+      })
+      .catch(error => {
+        this.logger.error('Failed to clean up entities', error);
+      });
+  }
+}

plugins/catalog-backend-module-github-org/src/module.ts

@@ -31,6 +31,7 @@ import {
 } from '@backstage/plugin-catalog-backend-module-github';
 import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node/alpha';
 import { eventsServiceRef } from '@backstage/plugin-events-node';
+import { GithubOrgEntityCleanerProvider } from './GithubOrgEntityCleanerProvider';
 
 /**
  * Interface for {@link githubOrgEntityProviderTransformsExtensionPoint}.
@@ -99,8 +100,14 @@ export const catalogModuleGithubOrgEntityProvider = createBackendModule({
         logger: coreServices.logger,
         scheduler: coreServices.scheduler,
       },
+
       async init({ catalog, config, events, logger, scheduler }) {
-        for (const definition of readDefinitionsFromConfig(config)) {
+        const definitions = readDefinitionsFromConfig(config);
+
+        for (const definition of definitions) {
+          catalog.addEntityProvider(
+            new GithubOrgEntityCleanerProvider({ id: definition.id, logger }),
+          );
           catalog.addEntityProvider(
             GithubMultiOrgEntityProvider.fromConfig(config, {
               id: definition.id,
@@ -113,6 +120,8 @@ export const catalogModuleGithubOrgEntityProvider = createBackendModule({
               logger,
               userTransformer,
               teamTransformer,
+              alwaysUseDefaultNamespace:
+                definitions.length === 1 && definition.orgs?.length === 1,
             }),
           );
         }

plugins/catalog-backend-module-github/api-report.md

@@ -150,6 +150,7 @@ export class GithubMultiOrgEntityProvider implements EntityProvider {
     orgs?: string[];
     userTransformer?: UserTransformer;
     teamTransformer?: TeamTransformer;
+    alwaysUseDefaultNamespace?: boolean;
   });
   // (undocumented)
   connect(connection: EntityProviderConnection): Promise<void>;
@@ -165,6 +166,7 @@ export class GithubMultiOrgEntityProvider implements EntityProvider {
 
 // @public
 export interface GithubMultiOrgEntityProviderOptions {
+  alwaysUseDefaultNamespace?: boolean;
   events?: EventsService;
   githubCredentialsProvider?: GithubCredentialsProvider;
   githubUrl: string;