[Catalog GitLab Org] Add extension point to override user and group transformers (#30892)

* feat: Add gitlabOrgEntityProviderTransformsExtensionPoint for overriding user and group transformers

Signed-off-by: Jack Palmer <jackpalmer@spotify.com>

* chore: Add changeset

Signed-off-by: Jack Palmer <jackpalmer@spotify.com>

* chore: Address pr comments

Signed-off-by: Jack Palmer <jackpalmer@spotify.com>

---------

Signed-off-by: Jack Palmer <jackpalmer@spotify.com>

.changeset/three-moons-hear.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-catalog-backend-module-gitlab-org': patch
+---
+
+feat: Add gitlabOrgEntityProviderTransformsExtensionPoint for overriding user and group transformers

plugins/catalog-backend-module-gitlab-org/report.api.md

@@ -4,8 +4,20 @@
 
 ```ts
 import { BackendFeature } from '@backstage/backend-plugin-api';
+import { ExtensionPoint } from '@backstage/backend-plugin-api';
+import { GroupTransformer } from '@backstage/plugin-catalog-backend-module-gitlab';
+import { UserTransformer } from '@backstage/plugin-catalog-backend-module-gitlab';
 
 // @public
 const catalogModuleGitlabOrgDiscoveryEntityProvider: BackendFeature;
 export default catalogModuleGitlabOrgDiscoveryEntityProvider;
+
+// @public
+export interface GitlabOrgEntityProviderTransformsExtensionPoint {
+  setGroupTransformer(transformer: GroupTransformer): void;
+  setUserTransformer(transformer: UserTransformer): void;
+}
+
+// @public
+export const gitlabOrgEntityProviderTransformsExtensionPoint: ExtensionPoint<GitlabOrgEntityProviderTransformsExtensionPoint>;
 ```

plugins/catalog-backend-module-gitlab-org/src/catalogModuleGitlabOrgDiscoveryEntityProvider.ts

@@ -17,11 +17,45 @@
 import {
   coreServices,
   createBackendModule,
+  createExtensionPoint,
 } from '@backstage/backend-plugin-api';
-import { GitlabOrgDiscoveryEntityProvider } from '@backstage/plugin-catalog-backend-module-gitlab';
+import {
+  GitlabOrgDiscoveryEntityProvider,
+  UserTransformer,
+  GroupTransformer,
+} from '@backstage/plugin-catalog-backend-module-gitlab';
 import { catalogProcessingExtensionPoint } from '@backstage/plugin-catalog-node/alpha';
 import { eventsServiceRef } from '@backstage/plugin-events-node';
 
+/**
+ * Interface for {@link gitlabOrgEntityProviderTransformsExtensionPoint}.
+ *
+ * @public
+ */
+export interface GitlabOrgEntityProviderTransformsExtensionPoint {
+  /**
+   * Set a custom transformer for transforming from GitLab users to catalog
+   * entities.
+   */
+  setUserTransformer(transformer: UserTransformer): void;
+
+  /**
+   * Set a custom transformer for transforming from GitLab groups to catalog
+   * entities.
+   */
+  setGroupTransformer(transformer: GroupTransformer): void;
+}
+
+/**
+ * Extension point for runtime configuration of GitlabOrgDiscoveryEntityProvider.
+ *
+ * @public
+ */
+export const gitlabOrgEntityProviderTransformsExtensionPoint =
+  createExtensionPoint<GitlabOrgEntityProviderTransformsExtensionPoint>({
+    id: 'catalog.gitlabOrgEntityProvider',
+  });
+
 /**
  * Registers the GitlabOrgDiscoveryEntityProvider with the catalog processing extension point.
  *
@@ -32,6 +66,27 @@ export const catalogModuleGitlabOrgDiscoveryEntityProvider =
     pluginId: 'catalog',
     moduleId: 'gitlabOrgDiscoveryEntityProvider',
     register(env) {
+      let userTransformer: UserTransformer | undefined;
+      let groupTransformer: GroupTransformer | undefined;
+
+      env.registerExtensionPoint(
+        gitlabOrgEntityProviderTransformsExtensionPoint,
+        {
+          setUserTransformer(transformer) {
+            if (userTransformer) {
+              throw new Error('User transformer may only be set once');
+            }
+            userTransformer = transformer;
+          },
+          setGroupTransformer(transformer) {
+            if (groupTransformer) {
+              throw new Error('Group transformer may only be set once');
+            }
+            groupTransformer = transformer;
+          },
+        },
+      );
+
       env.registerInit({
         deps: {
           config: coreServices.rootConfig,
@@ -46,6 +101,8 @@ export const catalogModuleGitlabOrgDiscoveryEntityProvider =
               logger,
               events,
               scheduler,
+              userTransformer,
+              groupEntitiesTransformer: groupTransformer,
             });
           catalog.addEntityProvider(gitlabOrgDiscoveryEntityProvider);
         },

plugins/catalog-backend-module-gitlab-org/src/index.ts

@@ -19,4 +19,8 @@
  *
  * @packageDocumentation
  */
-export { catalogModuleGitlabOrgDiscoveryEntityProvider as default } from './catalogModuleGitlabOrgDiscoveryEntityProvider';
+export {
+  catalogModuleGitlabOrgDiscoveryEntityProvider as default,
+  gitlabOrgEntityProviderTransformsExtensionPoint,
+  type GitlabOrgEntityProviderTransformsExtensionPoint,
+} from './catalogModuleGitlabOrgDiscoveryEntityProvider';