Merge pull request #25363 from elaine-mattos/feat/mirror-group-member-relation

Enhance GitLabOrgDiscoveryEntityProvider to More Accurately Mirror GitLab Membership Hierarchies

.changeset/loud-singers-happen.md

@@ -0,0 +1,16 @@
+---
+'@backstage/plugin-catalog-backend-module-gitlab': patch
+---
+
+Add the `relations` array to allow Backstage to mirror GitLab's membership behavior, including descendant, inherited, and shared-from-group memberships.
+
+The previous `allowInherited` config option will be deprecated in future versions. Use the `relations` array with the `INHERITED` option instead.
+
+```yaml
+catalog:
+  providers:
+    gitlab:
+      development:
+        relations:
+          - INHERITED
+```

docs/integrations/gitlab/org.md

@@ -171,7 +171,10 @@ catalog:
         host: gitlab.com
         orgEnabled: true
         group: org/teams # Required for gitlab.com when `orgEnabled: true`. Optional for self managed. Must not end with slash. Accepts only groups under the provided path (which will be stripped)
-        allowInherited: true # Allow groups to be ingested even if there are no direct members.
+        relations: # Optional
+          - INHERITED # Optional. Members of any ancestor groups will also be considered members of the current group.
+          - DESCENDANTS # Optional. Members of any descendant groups will also be considered members of the current group.
+          - SHARED_FROM_GROUPS # Optional. Members of any invited groups will also be considered members of the current group.
         groupPattern: '[\s\S]*' # Optional. Filters found groups based on provided pattern. Defaults to `[\s\S]*`, which means to not filter anything
         schedule: # Same options as in SchedulerServiceTaskScheduleDefinition. Optional for the Legacy Backend System.
           # supports cron, ISO duration, "human duration" as used in code
@@ -193,6 +196,32 @@ entities will only be ingested for the configured group, or its descendant group
 but not any ancestor groups higher than the configured group path. Only groups
 which contain members will be ingested.
 
+### Subgroup Membership
+
+GitLab groups and subgroups provide a hierarchical structure for organizing projects and users. Membership in a parent group extends automatically to its subgroups, ensuring consistent permissions at all levels. Additionally, membership can be managed using invited groups, where one group can be added to another. For Backstage users integrating with GitLab, understanding this [inheritance model](https://docs.gitlab.co.jp/ee/user/group/subgroups/#subgroup-membership) and the concept of invited groups is crucial for accurately mapping and managing group and user entities.
+
+The `GitLabOrgDiscoveryEntityProvider` mirrors GitLab's membership behavior as follows:
+
+- By default, every direct member of a GitLab group is also a member of the corresponding group in Backstage.
+- To include members of subgroups as members of the parent group, configure the `relations` array with the `DESCENDANTS` option.
+- To include members of parent groups as members of their subgroups, configure the `relations` array with the `INHERITED` option. This also has the effect that subgroups with no direct members will not be skipped in the group ingestion process and will be added as a group entity in Backstage;
+- To include members of invited groups as members of the inviting group, configure the `relations` array with the `SHARED_FROM_GROUPS` option.
+
+The previous `allowInherited` will be deprecated in future versions. Use the `relations` array with the `INHERITED` option instead.
+
+```yaml
+catalog:
+  providers:
+    gitlab:
+      development:
+        relations:
+          - INHERITED
+          - DESCENDANTS
+          - SHARED_FROM_GROUPS
+```
+
+Refer to the [GitLab Group Member Relation](https://docs.gitlab.com/ee/api/graphql/reference/#groupmemberrelation) documentation for more information.
+
 ### Users
 
 For self hosted, all `User` entities are ingested from the entire instance by default.

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

@@ -107,6 +107,7 @@ export type GitlabProviderConfig = {
   userPattern: RegExp;
   groupPattern: RegExp;
   allowInherited?: boolean;
+  relations?: string[];
   orgEnabled?: boolean;
   schedule?: SchedulerServiceTaskScheduleDefinition;
   skipForkedRepos?: boolean;

plugins/catalog-backend-module-gitlab/src/lib/types.ts

@@ -191,10 +191,41 @@ export type GitlabProviderConfig = {
   groupPattern: RegExp;
 
   /**
-   * If true, the provider will also ingest add inherited users to the ingested groups
-   */
+   * If true, the provider will also add inherited (ascendant) users to the ingested groups.
+   * See: https://docs.gitlab.com/ee/api/graphql/reference/#groupmemberrelation
+   *
+   * @deprecated Use the `relations` array to configure group membership relations instead.
+   **/
   allowInherited?: boolean;
 
+  /**
+   * Specifies the types of group membership relations that should be included when ingesting data.
+   *
+   * The following values are valid:
+   * - 'DIRECT': Direct members of the group. This is the default relation and is always included.
+   * - 'INHERITED': Members inherited from parent (ascendant) groups.
+   * - 'DESCENDANTS': Members from child (descendant) groups.
+   * - 'SHARED_FROM_GROUPS': Members shared from other groups.
+   *
+   * See: https://docs.gitlab.com/ee/api/graphql/reference/#groupmemberrelation
+   *
+   * If the `relations` array is provided in the app-config.yaml, it should contain any combination of the above values.
+   * The 'DIRECT' relation is automatically included and cannot be excluded, even if not specified.
+   * Example configuration:
+   *
+   * ```yaml
+   * catalog:
+   *   providers:
+   *     gitlab:
+   *       development:
+   *         relations:
+   *           - INHERITED
+   *           - DESCENDANTS
+   *           - SHARED_FROM_GROUPS
+   * ```
+   */
+  relations?: string[];
+
   orgEnabled?: boolean;
   schedule?: SchedulerServiceTaskScheduleDefinition;
   /**

plugins/catalog-backend-module-gitlab/src/providers/GitlabOrgDiscoveryEntityProvider.ts

@@ -445,9 +445,7 @@ export class GitlabOrgDiscoveryEntityProvider implements EntityProvider {
 
       let groupUsers: PagedResponse<GitLabUser> = { items: [] };
       try {
-        const relations = this.config.allowInherited
-          ? ['DIRECT', 'INHERITED']
-          : ['DIRECT'];
+        const relations = this.getRelations(this.config);
         groupUsers = await this.gitLabClient.getGroupMembers(
           group.full_path,
           relations,
@@ -724,9 +722,7 @@ export class GitlabOrgDiscoveryEntityProvider implements EntityProvider {
       return;
     }
 
-    const relations = this.config.allowInherited
-      ? ['DIRECT', 'INHERITED']
-      : ['DIRECT'];
+    const relations = this.getRelations(this.config);
 
     // fetch group members from GitLab
     const groupMembers = await this.gitLabClient.getGroupMembers(
@@ -802,4 +798,15 @@ export class GitlabOrgDiscoveryEntityProvider implements EntityProvider {
       entity,
     ) as Entity;
   }
+
+  private getRelations(config: any) {
+    if (Array.isArray(config.relations)) {
+      // filter out duplicates
+      const relationsSet = new Set(['DIRECT', ...config.relations]);
+      return Array.from(relationsSet);
+    }
+
+    // TODO: remove this fallback in the next major version by ensuring the method returns only `['DIRECT']` if no `relations` array is provided.
+    return ['DIRECT', ...(config.allowInherited ? ['INHERITED'] : [])];
+  }
 }

plugins/catalog-backend-module-gitlab/src/providers/config.test.ts

@@ -58,6 +58,7 @@ describe('config', () => {
         userPattern: /[\s\S]*/,
         orgEnabled: false,
         allowInherited: false,
+        relations: [],
         schedule: undefined,
         skipForkedRepos: false,
         excludeRepos: [],
@@ -98,6 +99,7 @@ describe('config', () => {
         userPattern: /[\s\S]*/,
         orgEnabled: false,
         allowInherited: false,
+        relations: [],
         schedule: undefined,
         skipForkedRepos: false,
         excludeRepos: [],
@@ -139,6 +141,7 @@ describe('config', () => {
         userPattern: /[\s\S]*/,
         orgEnabled: false,
         allowInherited: false,
+        relations: [],
         schedule: undefined,
         restrictUsersToGroup: false,
         excludeRepos: [],
@@ -181,6 +184,7 @@ describe('config', () => {
         userPattern: /[\s\S]*/,
         orgEnabled: false,
         allowInherited: false,
+        relations: [],
         schedule: undefined,
         restrictUsersToGroup: false,
         skipForkedRepos: false,
@@ -224,6 +228,7 @@ describe('config', () => {
         userPattern: /[\s\S]*/,
         orgEnabled: false,
         allowInherited: false,
+        relations: [],
         skipForkedRepos: false,
         restrictUsersToGroup: false,
         excludeRepos: [],

plugins/catalog-backend-module-gitlab/src/providers/config.ts

@@ -45,6 +45,8 @@ function readGitlabConfig(id: string, config: Config): GitlabProviderConfig {
   const orgEnabled: boolean = config.getOptionalBoolean('orgEnabled') ?? false;
   const allowInherited: boolean =
     config.getOptionalBoolean('allowInherited') ?? false;
+  const relations: string[] = config.getOptionalStringArray('relations') ?? [];
+
   const skipForkedRepos: boolean =
     config.getOptionalBoolean('skipForkedRepos') ?? false;
   const excludeRepos: string[] =
@@ -71,6 +73,7 @@ function readGitlabConfig(id: string, config: Config): GitlabProviderConfig {
     schedule,
     orgEnabled,
     allowInherited,
+    relations,
     skipForkedRepos,
     excludeRepos,
     restrictUsersToGroup,