API Request: Retrieve All Groups with Maintainer Role (Direct and Indirect)

Release notes

GitLab's API currently lacks a way to retrieve all groups where a user has the Maintainer role, including indirect memberships (e.g., inherited via group invitations). This proposal seeks to introduce an endpoint or make existing internal functionality public to address this limitation, improving integrations and automations.

Problem to solve

Currently, existing APIs like /groups and /users/:id/memberships only return groups where a user has direct membership. They exclude groups where Maintainer access is inherited via parent groups or invitations. This limitation makes it difficult to replicate the behavior seen in GitLab's UI programmatically.

Context This topic was previously discussed with GitLab Support under request #596228. In their response, the support team acknowledged the limitation in existing APIs and suggested creating this feature proposal to explore a solution.

Intended users

  • Developers who need to programmatically retrieve all groups where they have Maintainer access.

User experience goal

Allow users to retrieve all groups where a user has the Maintainer role programmatically, including both direct and indirect memberships, mirroring the functionality of GitLab's UI.

Proposal

  1. Make the searchNamespacesWhereUserCanCreateProjects internal API public.
  • This API already retrieves all groups (direct and invited) where a user can create projects, including indirect memberships.
  1. Introduce a new public API endpoint.
  • Similar to searchNamespacesWhereUserCanCreateProjects, but explicitly tailored to list groups where a user has the Maintainer role.

Further details

This feature is crucial for improving the integration of GitLab with external tools and automating workflows. Without it, users must resort to manual workarounds, such as directly adding users to groups, which can be time-consuming and error-prone.

Permissions and Security

This feature should:

Respect existing permissions. Only return groups where the requesting user has access to view membership details.

Documentation

  1. Add a new section in the API documentation to cover this feature.
  2. Clarify how it relates to existing APIs like /groups and /users/:id/memberships.

Availability & Testing

Unit tests: Validate the behavior of the new API endpoint. Integration tests: Ensure compatibility with other API endpoints and existing workflows.

Available Tier

  • Free
  • Premium/Silver
  • Ultimate/Gold

Feature Usage Metrics

Our organization uses Datadog for monitoring, and we can integrate this feature to track:

  • API call frequency.
  • Error rates or unusual patterns in usage.
  • Response times to ensure the API meets performance expectations.

What does success look like, and how can we measure that?

Success: Users can retrieve all groups (direct and invited) where they have Maintainer access programmatically. Metrics: Adoption of the new endpoint and reduction in related support tickets.

What is the type of buyer?

N/A (This proposal is aimed at improving existing functionality for developers and technical users.)

Is this a cross-stage feature?

N/A (This request focuses on the Groups API and does not involve multiple stage groups.)

What is the competitive advantage or differentiation for this feature?

N/A (This proposal enhances GitLab's current API to align with existing UI functionality, rather than introducing new competitive differentiation.)

Links / references

Support Request https://support.gitlab.com/hc/en-us/requests/596228 Internal endpoint: searchNamespacesWhereUserCanCreateProjects