Implementation:OpenHands OpenHands SaaSGitLabService

Knowledge Sources	OpenHands
Domains	Platform_Integration, GitLab
Last Updated	2026-02-11 21:00 GMT

Overview

SaaS-specific extension of the GitLab service that manages API tokens, group/project enumeration, and webhook record storage.

Description

SaaSGitLabService extends the base GitLabService with enterprise token management using a three-fallback strategy (external auth token, token manager refresh, direct token). It provides methods for fetching owned groups and projects with pagination, storing webhook records for groups and projects, and coordinating repository data storage.

Usage

Use this class when the OpenHands SaaS platform needs to interact with a user's GitLab instance, specifically for webhook management, repository enumeration, and token-managed API calls.

Code Reference

Source Location

• Repository: OpenHands
• File: enterprise/integrations/gitlab/gitlab_service.py
• Lines: 1-611

Signature

class SaaSGitLabService(GitLabService):
    def __init__(
        self,
        user_id: str | None = None,
        external_auth_token: SecretStr | None = None,
        external_auth_id: str | None = None,
        token: SecretStr | None = None,
        external_token_manager: bool = False,
        base_domain: str | None = None,
    ):
        ...

    async def get_latest_token(self) -> SecretStr | None:
        ...

    async def get_owned_groups(self, min_access_level: int = 40) -> list[dict]:
        ...

    async def add_owned_projects_and_groups_to_db(self, owned_personal_projects) -> None:
        ...

    async def store_repository_data(
        self,
        users_personal_projects: list[dict],
        repositories: list[Repository],
    ) -> None:
        ...

Import

from enterprise.integrations.gitlab.gitlab_service import SaaSGitLabService

I/O Contract

Inputs

Name	Type	Required	Description
user_id	str	No	Keycloak user identifier
external_auth_token	SecretStr	No	External authentication token
external_auth_id	str	No	External auth ID (e.g., Keycloak user ID)
token	SecretStr	No	Direct GitLab API token
external_token_manager	bool	No	Whether to use external token management
base_domain	str	No	GitLab instance domain

Outputs

Name	Type	Description
get_latest_token()	SecretStr or None	Current valid GitLab API token
get_owned_groups()	list[dict]	Top-level groups where user has admin access
store_repository_data()	None	Persists webhook and repository records to database

Usage Examples

from enterprise.integrations.gitlab.gitlab_service import SaaSGitLabService

# Initialize with external token management
service = SaaSGitLabService(
    user_id="user-123",
    external_auth_id="keycloak-456",
    external_token_manager=True,
    base_domain="gitlab.example.com",
)

# Fetch all groups with admin access
groups = await service.get_owned_groups(min_access_level=40)

# Store webhook records for discovered resources
await service.add_owned_projects_and_groups_to_db(owned_personal_projects=projects)

Related Pages

• Environment:OpenHands_OpenHands_Integration_Credentials