gitlab-api 25.23.0__tar.gz → 25.24.1__tar.gz

{gitlab_api-25.23.0/gitlab_api.egg-info → gitlab_api-25.24.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitlab-api
-Version: 25.23.0
+Version: 25.24.1
 Summary: GitLab API + MCP Server + A2A Server
 Author-email: Audel Rouhi <knucklessg1@gmail.com>
 License: MIT
@@ -12,11 +12,12 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: <3.14,>=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: agent-utilities>=0.9.0
+Requires-Dist: agent-utilities>=0.11.0
+Requires-Dist: python-dotenv>=1.0.0
 Provides-Extra: mcp
-Requires-Dist: agent-utilities[mcp]>=0.9.0; extra == "mcp"
+Requires-Dist: agent-utilities[mcp]>=0.11.0; extra == "mcp"
 Provides-Extra: agent
-Requires-Dist: agent-utilities[agent,logfire]>=0.9.0; extra == "agent"
+Requires-Dist: agent-utilities[agent,logfire]>=0.11.0; extra == "agent"
 Provides-Extra: gql
 Requires-Dist: gql>=4.0.0; extra == "gql"
 Provides-Extra: all
@@ -24,6 +25,7 @@ Requires-Dist: gitlab-api[agent,gql,logfire,mcp]>=25.15.56; extra == "all"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
 Dynamic: license-file
 
 # GitLab API - A2A | AG-UI | MCP
@@ -49,7 +51,7 @@ Dynamic: license-file
 ![PyPI - Wheel](https://img.shields.io/pypi/wheel/gitlab-api)
 ![PyPI - Implementation](https://img.shields.io/pypi/implementation/gitlab-api)
 
-*Version: 25.23.0*
+*Version: 25.24.1*
 
 ## Overview
 
@@ -880,6 +882,42 @@ For Testing Only: Plain text storage will also work, although **not** recommende
 }
 ```
 
+## Security & Governance
+
+This project is built on [`agent-utilities`](https://github.com/Knuckles-Team/agent-utilities), inheriting enterprise-grade security and governance features.
+
+### Authentication & Authorization
+| Feature | Description |
+|---------|-------------|
+| **OIDC Token Delegation** | RFC 8693 token exchange for user-context propagation from A2A → MCP |
+| **Eunomia Policies** | Fine-grained, policy-driven tool authorization (`none`, `embedded`, `remote`) |
+| **Scoped Credentials** | Tools execute with the caller's scoped identity where possible |
+| **3LO / OAuth / API Token** | Multiple auth strategies with graceful fallback |
+
+### Eunomia Policy Enforcement
+Eunomia provides a policy enforcement point for all tool calls:
+- **Embedded mode**: Load local `mcp_policies.json` for role-based access, sensitivity gating, and audit logging
+- **Remote mode**: Forward authorization decisions to a central Eunomia policy server for multi-agent governance
+- Enable via CLI: `--eunomia-type embedded --eunomia-policy-file mcp_policies.json`
+
+### Runtime Protections
+| Protection | Description |
+|------------|-------------|
+| **Tool Guard** | Sensitivity detection with human-in-the-loop approval gating |
+| **Prompt Injection Defense** | Input scanning and repetition/loop guards |
+| **Content Filtering** | Output schema enforcement and cost budget controls |
+| **Stuck Loop Detection** | Automatic detection and recovery from agent loops |
+| **Context Limit Warnings** | Proactive alerts before context window exhaustion |
+
+### Graph Agent Architecture
+The A2A agent uses `pydantic-graph` orchestration with:
+- **RouterNode**: Lightweight classifier that routes queries to specialized domains
+- **DomainNode**: Focused executor with only relevant tools loaded, preventing tool hallucination
+- **Approval Gates**: Policy-driven approval workflows before sensitive operations
+- **Usage Guards**: Budget and rate limiting enforcement
+
+> **Production Recommendation**: Enable `--eunomia-type embedded` (or `remote`) + OIDC delegation + containerized deployment. See [`agent-utilities` documentation](https://github.com/Knuckles-Team/agent-utilities) for full policy configuration.
+
 ## Install Python Package
 
 Install Python Package
@@ -931,103 +969,28 @@ npx @modelcontextprotocol/inspector gitlab-mcp
 
 ## MCP Configuration Examples
 
-### 1. Standard IO (stdio) Deployment
-
+### stdio (recommended for local development)
 ```json
 {
   "mcpServers": {
-    "gitlab-api": {
-      "command": "uv",
-      "args": [
-        "run",
-        "gitlab-mcp"
-      ],
+    "gitlab": {
+      "command": ".venv/bin/gitlab-mcp",
+      "args": [],
       "env": {
-        "AGENT_DESCRIPTION": "<YOUR_AGENT_DESCRIPTION>",
-        "AGENT_SYSTEM_PROMPT": "<YOUR_AGENT_SYSTEM_PROMPT>",
-        "BRANCHESTOOL": "True",
-        "COMMITSTOOL": "True",
-        "CUSTOM_APITOOL": "True",
-        "DEFAULT_AGENT_NAME": "<YOUR_DEFAULT_AGENT_NAME>",
-        "DEPLOY_TOKENSTOOL": "True",
-        "ENVIRONMENTSTOOL": "True",
-        "GITLAB_SSL_VERIFY": "<YOUR_GITLAB_SSL_VERIFY>",
-        "GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>",
-        "GITLAB_URL": "<YOUR_GITLAB_URL>",
-        "GITLAB_VERIFY": "<YOUR_GITLAB_VERIFY>",
-        "GROUPSTOOL": "True",
-        "JOBSTOOL": "True",
-        "LLM_API_KEY": "<YOUR_LLM_API_KEY>",
-        "LLM_BASE_URL": "<YOUR_LLM_BASE_URL>",
-        "MCP_URL": "<YOUR_MCP_URL>",
-        "MEMBERSTOOL": "True",
-        "MERGE_REQUESTSTOOL": "True",
-        "MERGE_RULESTOOL": "True",
-        "MISCTOOL": "True",
-        "MODEL_ID": "<YOUR_MODEL_ID>",
-        "PACKAGESTOOL": "True",
-        "PIPELINESTOOL": "True",
-        "PIPELINE_SCHEDULESTOOL": "True",
-        "PROJECTSTOOL": "True",
-        "PROTECTED_BRANCHESTOOL": "True",
-        "RELEASESTOOL": "True",
-        "RUNNERSTOOL": "True",
-        "TAGSTOOL": "True"
-      }
+        "GITLAB_URL": "",
+        "GITLAB_TOKEN": ""
+}
     }
   }
 }
 ```
 
-### 2. Streamable HTTP (SSE) Deployment
-
+### Streamable HTTP (recommended for production)
 ```json
 {
   "mcpServers": {
-    "gitlab-api": {
-      "command": "uv",
-      "args": [
-        "run",
-        "gitlab-mcp",
-        "--transport",
-        "http",
-        "--host",
-        "0.0.0.0",
-        "--port",
-        "8000"
-      ],
-      "env": {
-        "AGENT_DESCRIPTION": "<YOUR_AGENT_DESCRIPTION>",
-        "AGENT_SYSTEM_PROMPT": "<YOUR_AGENT_SYSTEM_PROMPT>",
-        "BRANCHESTOOL": "True",
-        "COMMITSTOOL": "True",
-        "CUSTOM_APITOOL": "True",
-        "DEFAULT_AGENT_NAME": "<YOUR_DEFAULT_AGENT_NAME>",
-        "DEPLOY_TOKENSTOOL": "True",
-        "ENVIRONMENTSTOOL": "True",
-        "GITLAB_SSL_VERIFY": "<YOUR_GITLAB_SSL_VERIFY>",
-        "GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>",
-        "GITLAB_URL": "<YOUR_GITLAB_URL>",
-        "GITLAB_VERIFY": "<YOUR_GITLAB_VERIFY>",
-        "GROUPSTOOL": "True",
-        "JOBSTOOL": "True",
-        "LLM_API_KEY": "<YOUR_LLM_API_KEY>",
-        "LLM_BASE_URL": "<YOUR_LLM_BASE_URL>",
-        "MCP_URL": "<YOUR_MCP_URL>",
-        "MEMBERSTOOL": "True",
-        "MERGE_REQUESTSTOOL": "True",
-        "MERGE_RULESTOOL": "True",
-        "MISCTOOL": "True",
-        "MODEL_ID": "<YOUR_MODEL_ID>",
-        "PACKAGESTOOL": "True",
-        "PIPELINESTOOL": "True",
-        "PIPELINE_SCHEDULESTOOL": "True",
-        "PROJECTSTOOL": "True",
-        "PROTECTED_BRANCHESTOOL": "True",
-        "RELEASESTOOL": "True",
-        "RUNNERSTOOL": "True",
-        "TAGSTOOL": "True"
-      }
+    "gitlab": {
+      "url": "http://localhost:8080/gitlab-mcp/mcp"
     }
   }
 }

{gitlab_api-25.23.0 → gitlab_api-25.24.1}/README.md

@@ -21,7 +21,7 @@
 ![PyPI - Wheel](https://img.shields.io/pypi/wheel/gitlab-api)
 ![PyPI - Implementation](https://img.shields.io/pypi/implementation/gitlab-api)
 
-*Version: 25.23.0*
+*Version: 25.24.1*
 
 ## Overview
 
@@ -852,6 +852,42 @@ For Testing Only: Plain text storage will also work, although **not** recommende
 }
 ```
 
+## Security & Governance
+
+This project is built on [`agent-utilities`](https://github.com/Knuckles-Team/agent-utilities), inheriting enterprise-grade security and governance features.
+
+### Authentication & Authorization
+| Feature | Description |
+|---------|-------------|
+| **OIDC Token Delegation** | RFC 8693 token exchange for user-context propagation from A2A → MCP |
+| **Eunomia Policies** | Fine-grained, policy-driven tool authorization (`none`, `embedded`, `remote`) |
+| **Scoped Credentials** | Tools execute with the caller's scoped identity where possible |
+| **3LO / OAuth / API Token** | Multiple auth strategies with graceful fallback |
+
+### Eunomia Policy Enforcement
+Eunomia provides a policy enforcement point for all tool calls:
+- **Embedded mode**: Load local `mcp_policies.json` for role-based access, sensitivity gating, and audit logging
+- **Remote mode**: Forward authorization decisions to a central Eunomia policy server for multi-agent governance
+- Enable via CLI: `--eunomia-type embedded --eunomia-policy-file mcp_policies.json`
+
+### Runtime Protections
+| Protection | Description |
+|------------|-------------|
+| **Tool Guard** | Sensitivity detection with human-in-the-loop approval gating |
+| **Prompt Injection Defense** | Input scanning and repetition/loop guards |
+| **Content Filtering** | Output schema enforcement and cost budget controls |
+| **Stuck Loop Detection** | Automatic detection and recovery from agent loops |
+| **Context Limit Warnings** | Proactive alerts before context window exhaustion |
+
+### Graph Agent Architecture
+The A2A agent uses `pydantic-graph` orchestration with:
+- **RouterNode**: Lightweight classifier that routes queries to specialized domains
+- **DomainNode**: Focused executor with only relevant tools loaded, preventing tool hallucination
+- **Approval Gates**: Policy-driven approval workflows before sensitive operations
+- **Usage Guards**: Budget and rate limiting enforcement
+
+> **Production Recommendation**: Enable `--eunomia-type embedded` (or `remote`) + OIDC delegation + containerized deployment. See [`agent-utilities` documentation](https://github.com/Knuckles-Team/agent-utilities) for full policy configuration.
+
 ## Install Python Package
 
 Install Python Package
@@ -903,103 +939,28 @@ npx @modelcontextprotocol/inspector gitlab-mcp
 
 ## MCP Configuration Examples
 
-### 1. Standard IO (stdio) Deployment
-
+### stdio (recommended for local development)
 ```json
 {
   "mcpServers": {
-    "gitlab-api": {
-      "command": "uv",
-      "args": [
-        "run",
-        "gitlab-mcp"
-      ],
+    "gitlab": {
+      "command": ".venv/bin/gitlab-mcp",
+      "args": [],
       "env": {
-        "AGENT_DESCRIPTION": "<YOUR_AGENT_DESCRIPTION>",
-        "AGENT_SYSTEM_PROMPT": "<YOUR_AGENT_SYSTEM_PROMPT>",
-        "BRANCHESTOOL": "True",
-        "COMMITSTOOL": "True",
-        "CUSTOM_APITOOL": "True",
-        "DEFAULT_AGENT_NAME": "<YOUR_DEFAULT_AGENT_NAME>",
-        "DEPLOY_TOKENSTOOL": "True",
-        "ENVIRONMENTSTOOL": "True",
-        "GITLAB_SSL_VERIFY": "<YOUR_GITLAB_SSL_VERIFY>",
-        "GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>",
-        "GITLAB_URL": "<YOUR_GITLAB_URL>",
-        "GITLAB_VERIFY": "<YOUR_GITLAB_VERIFY>",
-        "GROUPSTOOL": "True",
-        "JOBSTOOL": "True",
-        "LLM_API_KEY": "<YOUR_LLM_API_KEY>",
-        "LLM_BASE_URL": "<YOUR_LLM_BASE_URL>",
-        "MCP_URL": "<YOUR_MCP_URL>",
-        "MEMBERSTOOL": "True",
-        "MERGE_REQUESTSTOOL": "True",
-        "MERGE_RULESTOOL": "True",
-        "MISCTOOL": "True",
-        "MODEL_ID": "<YOUR_MODEL_ID>",
-        "PACKAGESTOOL": "True",
-        "PIPELINESTOOL": "True",
-        "PIPELINE_SCHEDULESTOOL": "True",
-        "PROJECTSTOOL": "True",
-        "PROTECTED_BRANCHESTOOL": "True",
-        "RELEASESTOOL": "True",
-        "RUNNERSTOOL": "True",
-        "TAGSTOOL": "True"
-      }
+        "GITLAB_URL": "",
+        "GITLAB_TOKEN": ""
+}
     }
   }
 }
 ```
 
-### 2. Streamable HTTP (SSE) Deployment
-
+### Streamable HTTP (recommended for production)
 ```json
 {
   "mcpServers": {
-    "gitlab-api": {
-      "command": "uv",
-      "args": [
-        "run",
-        "gitlab-mcp",
-        "--transport",
-        "http",
-        "--host",
-        "0.0.0.0",
-        "--port",
-        "8000"
-      ],
-      "env": {
-        "AGENT_DESCRIPTION": "<YOUR_AGENT_DESCRIPTION>",
-        "AGENT_SYSTEM_PROMPT": "<YOUR_AGENT_SYSTEM_PROMPT>",
-        "BRANCHESTOOL": "True",
-        "COMMITSTOOL": "True",
-        "CUSTOM_APITOOL": "True",
-        "DEFAULT_AGENT_NAME": "<YOUR_DEFAULT_AGENT_NAME>",
-        "DEPLOY_TOKENSTOOL": "True",
-        "ENVIRONMENTSTOOL": "True",
-        "GITLAB_SSL_VERIFY": "<YOUR_GITLAB_SSL_VERIFY>",
-        "GITLAB_TOKEN": "<YOUR_GITLAB_TOKEN>",
-        "GITLAB_URL": "<YOUR_GITLAB_URL>",
-        "GITLAB_VERIFY": "<YOUR_GITLAB_VERIFY>",
-        "GROUPSTOOL": "True",
-        "JOBSTOOL": "True",
-        "LLM_API_KEY": "<YOUR_LLM_API_KEY>",
-        "LLM_BASE_URL": "<YOUR_LLM_BASE_URL>",
-        "MCP_URL": "<YOUR_MCP_URL>",
-        "MEMBERSTOOL": "True",
-        "MERGE_REQUESTSTOOL": "True",
-        "MERGE_RULESTOOL": "True",
-        "MISCTOOL": "True",
-        "MODEL_ID": "<YOUR_MODEL_ID>",
-        "PACKAGESTOOL": "True",
-        "PIPELINESTOOL": "True",
-        "PIPELINE_SCHEDULESTOOL": "True",
-        "PROJECTSTOOL": "True",
-        "PROTECTED_BRANCHESTOOL": "True",
-        "RELEASESTOOL": "True",
-        "RUNNERSTOOL": "True",
-        "TAGSTOOL": "True"
-      }
+    "gitlab": {
+      "url": "http://localhost:8080/gitlab-mcp/mcp"
     }
   }
 }

gitlab_api-25.24.1/gitlab_api/__init__.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python
+
+import importlib
+import inspect
+from typing import Any
+
+__all__: list[str] = []
+
+CORE_MODULES: list[str] = [
+    "gitlab_api.gitlab_input_models",
+    "gitlab_api.gitlab_response_models",
+    "gitlab_api.api_client",
+]
+
+OPTIONAL_MODULES = {
+    "gitlab_api.gitlab_gql": "gql",
+    "gitlab_api.agent_server": "agent",
+    "gitlab_api.mcp_server": "mcp",
+}
+
+
+def _expose_members(module):
+    """Expose public classes and functions from a module into globals and __all__."""
+    for name, obj in inspect.getmembers(module):
+        if (inspect.isclass(obj) or inspect.isfunction(obj)) and not name.startswith(
+            "_"
+        ):
+            globals()[name] = obj
+            if name not in __all__:
+                __all__.append(name)
+
+
+# Eagerly import core modules (keeps API wrappers fast & light)
+for module_name in CORE_MODULES:
+    if module_name:
+        module = importlib.import_module(module_name)
+        _expose_members(module)
+
+# Dynamic/lazy loading of optional modules (agent_server, mcp_server)
+_loaded_optional_modules = {}
+
+
+def _import_module_safely(module_name: str):
+    """Try to import a module and return it, or None if not available."""
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+
+def __getattr__(name: str) -> Any:
+    # Handle availability flags dynamically without eager imports
+    if name == "_MCP_AVAILABLE":
+        mcp_key = next((k for k in OPTIONAL_MODULES if "mcp_server" in k), None)
+        if mcp_key:
+            return _import_module_safely(mcp_key) is not None
+        return False
+    if name == "_AGENT_AVAILABLE":
+        agent_key = next((k for k in OPTIONAL_MODULES if "agent_server" in k), None)
+        if agent_key:
+            return _import_module_safely(agent_key) is not None
+        return False
+
+    # Check optional modules
+    for module_name in OPTIONAL_MODULES:
+        if module_name not in _loaded_optional_modules:
+            module = _import_module_safely(module_name)
+            if module is not None:
+                _loaded_optional_modules[module_name] = module
+                _expose_members(module)
+
+        module = _loaded_optional_modules.get(module_name)
+        if module is not None and hasattr(module, name):
+            return getattr(module, name)
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(list(globals().keys()) + __all__)

{gitlab_api-25.23.0 → gitlab_api-25.24.1}/gitlab_api/agent_server.py

@@ -4,15 +4,7 @@ import os
 import sys
 import warnings
 
-from agent_utilities import (
-    build_system_prompt_from_workspace,
-    create_agent_parser,
-    create_graph_agent_server,
-    initialize_workspace,
-    load_identity,
-)
-
-__version__ = "25.23.0"
+__version__ = "25.24.1"
 
 logging.basicConfig(
     level=logging.INFO,
@@ -22,23 +14,36 @@ logging.basicConfig(
 logger = logging.getLogger(__name__)
 
 
-initialize_workspace()
-meta = load_identity()
-DEFAULT_AGENT_NAME = os.getenv("DEFAULT_AGENT_NAME", meta.get("name", "Gitlab Api"))
-DEFAULT_AGENT_DESCRIPTION = os.getenv(
-    "AGENT_DESCRIPTION",
-    meta.get(
-        "description",
-        "AI agent for GitLab Api management.",
-    ),
-)
-DEFAULT_AGENT_SYSTEM_PROMPT = os.getenv(
-    "AGENT_SYSTEM_PROMPT",
-    meta.get("content") or build_system_prompt_from_workspace(),
-)
+DEFAULT_AGENT_NAME = None
+DEFAULT_AGENT_DESCRIPTION = None
+DEFAULT_AGENT_SYSTEM_PROMPT = None
 
 
 def agent_server():
+    from agent_utilities import (
+        build_system_prompt_from_workspace,
+        create_agent_parser,
+        create_agent_server,
+        initialize_workspace,
+        load_identity,
+    )
+
+    global DEFAULT_AGENT_NAME, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_SYSTEM_PROMPT
+    initialize_workspace()
+    meta = load_identity()
+    DEFAULT_AGENT_NAME = os.getenv("DEFAULT_AGENT_NAME", meta.get("name", "Gitlab Api"))
+    DEFAULT_AGENT_DESCRIPTION = os.getenv(
+        "AGENT_DESCRIPTION",
+        meta.get(
+            "description",
+            "AI agent for GitLab Api management.",
+        ),
+    )
+    DEFAULT_AGENT_SYSTEM_PROMPT = os.getenv(
+        "AGENT_SYSTEM_PROMPT",
+        meta.get("content") or build_system_prompt_from_workspace(),
+    )
+
     warnings.filterwarnings("ignore", message=".*urllib3.*or chardet.*")
     warnings.filterwarnings("ignore", category=DeprecationWarning, module="fastmcp")
 
@@ -51,7 +56,7 @@ def agent_server():
         logger.debug("Debug mode enabled")
 
     # Start server using the auto-discovery pattern (from mcp_config.json)
-    create_graph_agent_server(
+    create_agent_server(
         mcp_url=args.mcp_url,
         mcp_config=args.mcp_config or "mcp_config.json",
         host=args.host,

{gitlab_api-25.23.0 → gitlab_api-25.24.1}/gitlab_api/api_client.py

@@ -3456,6 +3456,36 @@ class Api:
         except ValidationError as e:
             raise ParameterError(f"Invalid parameters: {e.errors()}") from e
 
+    @require_auth
+    def delete_shared_project_link(self, **kwargs) -> Response:
+        """
+        Unshare a specific project from a group.
+
+        Args:
+            **kwargs: Additional parameters for the request (e.g., project_id, group_id).
+
+        Returns:
+            Response: A wrapper containing the original response (no data for successful deletion).
+
+        Raises:
+            MissingParameterError: If the project_id or group_id is missing.
+            ParameterError: If invalid parameters are provided.
+        """
+        project = ProjectModel(**kwargs)
+        if project.project_id is None or project.group_id is None:
+            raise MissingParameterError
+        try:
+            response = self._session.delete(
+                url=f"{self.url}/projects/{project.project_id}/share/{project.group_id}",
+                headers=self.headers,
+                verify=self.verify,
+                proxies=self.proxies,
+            )
+            response.raise_for_status()
+            return Response(response=response)
+        except ValidationError as e:
+            raise ParameterError(f"Invalid parameters: {e.errors()}") from e
+
     @require_auth
     def get_protected_branches(self, **kwargs) -> Response:
         """

gitlab_api-25.24.1/gitlab_api/auth.py

@@ -0,0 +1,132 @@
+"""GitLab Authentication Module.
+
+Authentication priority:
+1. **OIDC Delegation** — If ``ENABLE_DELEGATION`` is active, exchanges
+   the IdP-issued user token for a downstream GitLab access token
+   via RFC 8693 Token Exchange using the shared ``delegated_auth`` helper.
+2. **Fixed Credentials** — Falls back to ``GITLAB_TOKEN`` env var.
+
+See ``docs/guides/oauth_sso.md`` in agent-utilities for full details.
+"""
+
+import os
+import threading
+from typing import Any
+
+from agent_utilities.base_utilities import get_logger, to_boolean
+from agent_utilities.core.exceptions import AuthError, UnauthorizedError
+
+local = threading.local()
+from gitlab_api.api_client import Api
+
+logger = get_logger(__name__)
+
+
+def get_client(
+    instance: str = os.getenv("GITLAB_URL", "https://gitlab.com"),
+    token: str | None = os.getenv("GITLAB_TOKEN", None),
+    verify: bool = to_boolean(string=os.getenv("GITLAB_SSL_VERIFY", "True")),
+    config: dict | None = None,
+) -> Api:
+    """Factory function to create the GitLab Api client.
+
+    Supports OIDC delegation and fixed credentials (token).
+    Uses the shared ``delegated_auth`` helper from agent-utilities.
+    """
+    from agent_utilities.mcp.delegated_auth import (
+        get_delegated_token,
+        get_user_identity,
+        is_delegation_enabled,
+    )
+
+    # Resolve delegation config — prefer shared mcp_auth_config
+    delegation_enabled = is_delegation_enabled(config)
+
+    # --- Path 1: OIDC Delegation (RFC 8693 Token Exchange) ---
+    if delegation_enabled:
+        try:
+            delegated_token = get_delegated_token(
+                config=config,
+                audience=(config or {}).get("audience", instance),
+                scopes=(config or {}).get("delegated_scopes", "api"),
+                verify=verify,
+            )
+            identity = get_user_identity()
+            logger.info(
+                "Using OIDC delegated token for GitLab API",
+                extra={
+                    "user_email": identity.get("email"),
+                    "instance": instance,
+                },
+            )
+            return Api(url=instance, token=delegated_token, verify=verify)
+        except Exception as e:
+            logger.error(
+                "OIDC delegation failed for GitLab",
+                extra={"error_type": type(e).__name__, "error_message": str(e)},
+            )
+            raise RuntimeError(f"Token exchange failed: {str(e)}") from e
+
+    # --- Path 2: Fixed Credentials (GITLAB_TOKEN) ---
+    logger.info("Using fixed credentials for GitLab API")
+    try:
+        return Api(url=instance, token=token, verify=verify)
+    except (AuthError, UnauthorizedError) as e:
+        raise RuntimeError(
+            f"AUTHENTICATION ERROR: The GitLab credentials provided are not valid for '{instance}'. "
+            f"Please check your GITLAB_TOKEN and GITLAB_URL environment variables. "
+            f"Error details: {str(e)}"
+        ) from e
+
+
+def get_graphql_client(
+    instance: str = os.getenv("GITLAB_URL", "https://gitlab.com"),
+    token: str | None = os.getenv("GITLAB_TOKEN", None),
+    verify: bool = to_boolean(string=os.getenv("GITLAB_SSL_VERIFY", "True")),
+    config: dict | None = None,
+) -> Any:
+    """Factory function to create the GitLab GraphQL client.
+
+    Supports OIDC delegation and fixed credentials (token).
+    """
+    from agent_utilities.mcp.delegated_auth import (
+        get_delegated_token,
+        get_user_identity,
+        is_delegation_enabled,
+    )
+
+    from gitlab_api.gitlab_gql import GraphQL
+
+    # Resolve delegation config — prefer shared mcp_auth_config
+    delegation_enabled = is_delegation_enabled(config)
+
+    # --- Path 1: OIDC Delegation (RFC 8693 Token Exchange) ---
+    if delegation_enabled:
+        try:
+            delegated_token = get_delegated_token(
+                config=config,
+                audience=(config or {}).get("audience", instance),
+                scopes=(config or {}).get("delegated_scopes", "api"),
+                verify=verify,
+            )
+            identity = get_user_identity()
+            logger.info(
+                "Using OIDC delegated token for GitLab GraphQL API",
+                extra={
+                    "user_email": identity.get("email"),
+                    "instance": instance,
+                },
+            )
+            return GraphQL(url=instance, token=delegated_token, verify=verify)
+        except Exception as e:
+            logger.error(
+                "OIDC delegation failed for GitLab GraphQL",
+                extra={"error_type": type(e).__name__, "error_message": str(e)},
+            )
+            raise RuntimeError(f"Token exchange failed: {str(e)}") from e
+
+    # --- Path 2: Fixed Credentials (GITLAB_TOKEN) ---
+    logger.info("Using fixed credentials for GitLab GraphQL API")
+    if not token:
+        raise RuntimeError("GITLAB_TOKEN environment variable or parameter is missing.")
+    return GraphQL(url=instance, token=token, verify=verify)