> ## Documentation Index
> Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingest users and groups

> Configure the GitLab catalog provider to import users and groups from GitLab into Portal.

export const providerName_0 = "GitLab"

<Warning>
  It is important to follow all the steps in this guide to ensure a successful configuration of {providerName_0} authentication.

  If you encounter any issues, [please contact support](https://backstage.spotify.com/account/support/).
</Warning>

Portal can ingest organizational data, such as users and groups, from GitLab. This lets Portal resolve GitLab sign-ins to catalog user entities and apply ownership or admin access to GitLab-backed groups.

## Prerequisites

Before configuring the catalog provider, make sure the GitLab integration is configured in Portal under App Settings > Integrations.

The GitLab token used by the integration must have the `read_api` scope and access to the groups and users you want Portal to ingest.

## Configure the GitLab Org Provider in Portal

This setup uses the same Catalog Settings > Providers flow covered in [Setup GitLab Discovery](/docs/portal/guides/integrations/gitlab/gitlab-discovery). If you already configured GitLab auto-discovery, use the same host and provider settings as your starting point.

1. In Catalog Settings, go to the GitLab provider
2. Add a new provider configuration
3. Fill in the required provider details:
   * `Provider ID` - Use `default` to get started
   * `Host` - Use the default `gitlab.com` value for GitLab SaaS, or your self-managed GitLab hostname
   * `Group` - For GitLab.com, enter the group path that contains the users and groups Portal should ingest
   * `Schedule` - Use the default schedule to get started, then adjust the refresh frequency and timeout later if needed
4. Save the provider configuration

## Enable the GitLab Org Module

1. In Portal, go to Plugins
2. Open Catalog
3. Select Modules
4. Open `@backstage/plugin-catalog-backend-module-gitlab`
5. Under the provider key you want to enable, set `orgEnabled` to `true`
6. Save the module configuration

Portal will begin ingesting and synchronizing user and group data from GitLab according to the configured schedule.

## Notes

For GitLab.com, use `Group` to limit ingestion to your organization or team path. For self-managed GitLab, the group can be used to narrow ingestion when you do not want Portal to scan the whole instance.

The upstream Backstage provider supports additional options for group relations and user filtering. See the [Backstage GitLab Organizational Data documentation](https://backstage.io/docs/integrations/gitlab/org/) for more details.

## Next Steps

Your Portal instance should now have users and groups from GitLab within the catalog.

Continue to the next section to learn how to configure GitLab as the authentication provider in Portal.