chore: import upstream snapshot with attribution

integrations/gitlab/__init__.py

@@ -0,0 +1,260 @@
+"""Shared gitlab integration helpers."""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+from pydantic import Field, field_validator
+
+from config.strict_config import StrictConfigModel
+from integrations._validation_helpers import report_classify_failure, report_validation_failure
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_GITLAB_BASE_URL = "https://gitlab.com/api/v4"
+
+
+class GitlabConfig(StrictConfigModel):
+    """Normalized Gitlab connection settings."""
+
+    base_url: str = DEFAULT_GITLAB_BASE_URL
+    auth_token: str = ""
+    timeout_seconds: float = Field(default=15.0, gt=0)
+
+    @field_validator("base_url", mode="before")
+    @classmethod
+    def _normalize_base_url(cls, value: Any) -> str:
+        normalized = str(value or DEFAULT_GITLAB_BASE_URL).strip()
+        return normalized or DEFAULT_GITLAB_BASE_URL
+
+    @property
+    def api_base_url(self) -> str:
+        return self.base_url.rstrip("/")
+
+    @property
+    def auth_headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.auth_token}",
+            "Accept": "application/json",
+        }
+
+
+@dataclass(frozen=True)
+class GitlabValidationResult:
+    """Result of validating a Gitlab integration."""
+
+    ok: bool
+    detail: str
+
+
+def build_gitlab_config(raw: dict[str, Any] | None) -> GitlabConfig:
+    """Build a normalized Gitlab config object from env/store data."""
+    return GitlabConfig.model_validate(raw or {})
+
+
+def gitlab_config_from_env() -> GitlabConfig | None:
+    """Load a Gitlab config from env vars."""
+    auth_token = os.getenv("GITLAB_ACCESS_TOKEN", "").strip()
+    if not auth_token:
+        return None
+    return build_gitlab_config(
+        {
+            "base_url": os.getenv("GITLAB_BASE_URL", DEFAULT_GITLAB_BASE_URL).strip()
+            or DEFAULT_GITLAB_BASE_URL,
+            "auth_token": auth_token,
+        }
+    )
+
+
+def _request_json(
+    config: GitlabConfig,
+    method: str,
+    path: str,
+    *,
+    params: list[tuple[str, str | int | float | bool | None]] | None = None,
+    json: dict | None = None,
+) -> Any:
+    url = f"{config.api_base_url}{path}"
+    response = httpx.request(
+        method,
+        url,
+        json=json,
+        headers=config.auth_headers,
+        params=params,
+        timeout=config.timeout_seconds,
+    )
+    response.raise_for_status()
+    return response.json()
+
+
+def validate_gitlab_config(config: GitlabConfig) -> GitlabValidationResult:
+    """Validate gitlab connectivity with a lightweight user query."""
+
+    if not config.auth_token:
+        return GitlabValidationResult(ok=False, detail="Gitlab auth token is required.")
+
+    try:
+        user = validate_gitlab_connection(config=config)
+        username = user.get("username", "unknown")
+        return GitlabValidationResult(
+            ok=True, detail=f"GitLab connectivity successful. Authenticated as @{username}"
+        )
+    except httpx.HTTPStatusError as err:
+        detail = err.response.text.strip() or str(err)
+        return GitlabValidationResult(ok=False, detail=f"Gitlab validation failed: {detail}")
+    except Exception as err:
+        report_validation_failure(
+            err,
+            logger=logger,
+            integration="gitlab",
+            method="validate_gitlab_config",
+        )
+        return GitlabValidationResult(ok=False, detail=f"Gitlab validation failed: {err}")
+
+
+def validate_gitlab_connection(
+    *,
+    config: GitlabConfig,
+) -> dict[str, Any]:
+    """Validate gitlab connection."""
+
+    payload = _request_json(
+        config,
+        "GET",
+        "/user",
+    )
+    return payload if isinstance(payload, dict) else {}
+
+
+def get_gitlab_commits(
+    *, config: GitlabConfig, project_id: str, ref_name="main", since: str, per_page: int = 10
+) -> list[dict[str, Any]]:
+    """Fetch gitlab commits for project."""
+
+    encoded_project_id = quote(project_id, safe="")
+    params: list[tuple[str, str | int | float | bool | None]] = [
+        ("ref_name", ref_name),
+        ("per_page", per_page),
+    ]
+    if since:
+        params.append(("since", since))
+    payload = _request_json(
+        config,
+        "GET",
+        f"/projects/{encoded_project_id}/repository/commits",
+        params=params,
+    )
+    return payload if isinstance(payload, list) else []
+
+
+def get_gitlab_mrs(
+    *,
+    config: GitlabConfig,
+    project_id: str,
+    state: str = "merged",
+    target_branch: str = "main",
+    updated_after: str,
+    per_page: int = 10,
+) -> list[dict[str, Any]]:
+    """Fetch gitlab Merge requests for project."""
+
+    encoded_project_id = quote(project_id, safe="")
+    params: list[tuple[str, str | int | float | bool | None]] = [
+        ("state", state),
+        ("target_branch", target_branch),
+        ("per_page", per_page),
+    ]
+    if updated_after:
+        params.append(("updated_after", updated_after))
+    payload = _request_json(
+        config,
+        "GET",
+        f"/projects/{encoded_project_id}/merge_requests",
+        params=params,
+    )
+    return payload if isinstance(payload, list) else []
+
+
+def get_gitlab_pipelines(
+    *,
+    config: GitlabConfig,
+    project_id: str,
+    ref: str = "main",
+    status: str = "failed",
+    updated_after: str,
+    per_page: int = 5,
+) -> list[dict[str, Any]]:
+    """Fetch gitlab pipelines for project."""
+
+    encoded_project_id = quote(project_id, safe="")
+    params: list[tuple[str, str | int | float | bool | None]] = [
+        ("status", status),
+        ("ref", ref),
+        ("per_page", per_page),
+    ]
+    if updated_after:
+        params.append(("updated_after", updated_after))
+    payload = _request_json(
+        config,
+        "GET",
+        f"/projects/{encoded_project_id}/pipelines",
+        params=params,
+    )
+    return payload if isinstance(payload, list) else []
+
+
+def get_gitlab_file(
+    *,
+    config: GitlabConfig,
+    project_id: str,
+    ref: str = "main",
+    file_path: str,
+) -> dict[str, Any]:
+    """Fetch particular gitlab file"""
+
+    encoded_project_id = quote(project_id, safe="")
+    encoded_path = quote(file_path, safe="")
+    payload = _request_json(
+        config,
+        "GET",
+        f"/projects/{encoded_project_id}/repository/files/{encoded_path}",
+        params=[
+            ("ref", ref),
+        ],
+    )
+    return payload if isinstance(payload, dict) else {}
+
+
+def post_gitlab_mr_note(
+    *, config: GitlabConfig, project_id: str, mr_iid: str, body: str
+) -> dict[str, Any]:
+    """Post findings back on mr as comment"""
+
+    encoded_project_id = quote(project_id, safe="")
+    json_body = {"body": body}
+    payload = _request_json(
+        config,
+        "POST",
+        f"/projects/{encoded_project_id}/merge_requests/{mr_iid}/notes",
+        json=json_body,
+    )
+    return payload if isinstance(payload, dict) else {}
+
+
+def classify(credentials: dict[str, Any], record_id: str) -> tuple[GitlabConfig | None, str | None]:
+    try:
+        cfg = build_gitlab_config(
+            {
+                "base_url": credentials.get("base_url", ""),
+                "auth_token": credentials.get("auth_token", ""),
+            }
+        )
+    except Exception as exc:
+        report_classify_failure(exc, logger=logger, integration="gitlab", record_id=record_id)
+        return None, None
+    return cfg, "gitlab"

integrations/gitlab/tools/gitlab_commits_tool/__init__.py

@@ -0,0 +1,102 @@
+"""gitlab repository investigation tools."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from core.tool_framework.tool_decorator import tool
+from integrations.gitlab import (
+    GitlabConfig,
+    build_gitlab_config,
+    get_gitlab_commits,
+    gitlab_config_from_env,
+)
+
+
+def _gl_creds(gl: dict) -> dict:
+    return {
+        "gitlab_url": gl.get("gitlab_url"),
+        "gitlab_token": gl.get("gitlab_token"),
+    }
+
+
+def _gitlab_available(sources: dict) -> bool:
+    return bool(sources.get("gitlab", {}).get("connection_verified"))
+
+
+def _resolve_config(gitlab_url: str | None, gitlab_token: str | None) -> GitlabConfig | None:
+    env_config = gitlab_config_from_env()
+    if any([gitlab_url, gitlab_token]):
+        return build_gitlab_config(
+            {
+                "base_url": gitlab_url or (env_config.base_url if env_config else ""),
+                "auth_token": gitlab_token or (env_config.auth_token if env_config else ""),
+            }
+        )
+    return env_config
+
+
+def _list_gitlab_commits_extract_params(sources: dict[str, dict]) -> dict[str, Any]:
+    gl = sources["gitlab"]
+    return {
+        "project_id": gl["project_id"],
+        "since": gl.get("since", ""),
+        "ref_name": gl.get("ref_name", "main"),
+        "per_page": 10,
+        **_gl_creds(gl),
+    }
+
+
+def _list_gitlab_commits_available(sources: dict[str, dict]) -> bool:
+    gl = sources.get("gitlab", {})
+    return bool(_gitlab_available(sources) and gl.get("project_id"))
+
+
+@tool(
+    name="list_gitlab_commits",
+    source="gitlab",
+    description="List recent commits for a gitlab repository.",
+    use_cases=[
+        "Checking whether a recent change could explain a failure",
+        "Correlating a deployment or incident window with code changes",
+    ],
+    requires=["project_id"],
+    surfaces=("investigation", "chat"),
+    input_schema={
+        "type": "object",
+        "properties": {
+            "project_id": {"type": "string"},
+            "ref_name": {"type": "string", "default": ""},
+            "since": {"type": "string"},
+            "per_page": {"type": "integer", "default": 10},
+            "gitlab_url": {"type": "string"},
+            "gitlab_token": {"type": "string"},
+        },
+        "required": ["project_id"],
+    },
+    is_available=_list_gitlab_commits_available,
+    extract_params=_list_gitlab_commits_extract_params,
+)
+def list_gitlab_commits(
+    project_id: str,
+    ref_name: str = "main",
+    since: str = "",
+    per_page: int = 10,
+    gitlab_url: str | None = None,
+    gitlab_token: str | None = None,
+    **_kwargs: Any,
+) -> dict[str, Any]:
+    """List recent commits for a Gitlab repository"""
+    config = _resolve_config(gitlab_url, gitlab_token)
+    if config is None:
+        return {
+            "source": "gitlab",
+            "available": False,
+            "error": "gitlab integration is not configured.",
+            "commits": [],
+        }
+
+    result = get_gitlab_commits(
+        config=config, project_id=project_id, ref_name=ref_name, since=since, per_page=per_page
+    )
+    return {"source": "gitlab", "available": True, "commits": result}

integrations/gitlab/tools/gitlab_file_tool/__init__.py

@@ -0,0 +1,115 @@
+"""gitlab repository investigation tools."""
+
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+from core.tool_framework.tool_decorator import tool
+from core.tool_framework.utils.code_host_unavailable import code_host_unavailable_payload
+from integrations.gitlab import (
+    get_gitlab_file,
+)
+from integrations.gitlab.tools.gitlab_commits_tool import (
+    _gitlab_available,
+    _gl_creds,
+    _resolve_config,
+)
+
+
+def _get_gitlab_file_extract_params(sources: dict[str, dict]) -> dict[str, Any]:
+    gl = sources["gitlab"]
+    return {
+        "project_id": gl["project_id"],
+        "file_path": gl.get("file_path", ""),
+        "ref": gl.get("ref_name", "main"),
+        **_gl_creds(gl),
+    }
+
+
+def _get_gitlab_file_available(sources: dict[str, dict]) -> bool:
+    gl = sources.get("gitlab", {})
+    return bool(_gitlab_available(sources) and gl.get("project_id") and gl.get("file_path"))
+
+
+@tool(
+    name="get_gitlab_file",
+    source="gitlab",
+    description="Read the contents of a specific file from a GitLab repository.",
+    use_cases=[
+        "Reading a config file that may explain a misconfiguration causing the incident",
+        "Inspecting a schema or manifest file referenced in the alert error message",
+        "Viewing a specific version of a file at the deployed commit or branch",
+    ],
+    requires=["project_id", "file_path"],
+    surfaces=("investigation", "chat"),
+    input_schema={
+        "type": "object",
+        "properties": {
+            "project_id": {"type": "string"},
+            "file_path": {"type": "string"},
+            "ref": {"type": "string", "default": "main"},
+            "gitlab_url": {"type": "string"},
+            "gitlab_token": {"type": "string"},
+        },
+        "required": ["project_id", "file_path"],
+    },
+    is_available=_get_gitlab_file_available,
+    extract_params=_get_gitlab_file_extract_params,
+)
+def get_gitlab_file_contents(
+    project_id: str,
+    file_path: str,
+    ref: str = "main",
+    gitlab_url: str | None = None,
+    gitlab_token: str | None = None,
+    **_kwargs: Any,
+) -> dict[str, Any]:
+    """Read the contents of a specific file from a GitLab repository."""
+    config = _resolve_config(gitlab_url, gitlab_token)
+    if config is None:
+        return code_host_unavailable_payload(
+            source="gitlab",
+            integration_name="gitlab",
+            empty_key="file",
+            empty_value={},
+        )
+
+    result = get_gitlab_file(
+        config=config,
+        project_id=project_id,
+        ref=ref,
+        file_path=file_path,
+    )
+    if result.get("size", 0) > 50_000:
+        return {
+            "source": "gitlab",
+            "available": False,
+            "error": f"File too large to read ({result['size']} bytes)",
+            "file": {},
+        }
+
+    content_raw = result.get("content", "")
+    if content_raw:
+        try:
+            content_decoded = base64.b64decode(content_raw).decode("utf-8")
+        except UnicodeDecodeError:
+            return {
+                "source": "gitlab",
+                "available": False,
+                "error": f"File '{file_path}' is not UTF-8 text (binary file); cannot display contents.",
+                "file": {},
+            }
+    else:
+        content_decoded = ""
+
+    return {
+        "source": "gitlab",
+        "available": True,
+        "file": {
+            "file_name": result.get("file_name"),
+            "file_path": result.get("file_path"),
+            "ref": result.get("ref"),
+            "content": content_decoded,
+        },
+    }

integrations/gitlab/tools/gitlab_mrs_tool/__init__.py

@@ -0,0 +1,86 @@
+"""gitlab repository investigation tools."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from core.tool_framework.tool_decorator import tool
+from integrations.gitlab import (
+    get_gitlab_mrs,
+)
+from integrations.gitlab.tools.gitlab_commits_tool import (
+    _gitlab_available,
+    _gl_creds,
+    _resolve_config,
+)
+
+
+def _list_gitlab_mrs_extract_params(sources: dict[str, dict]) -> dict[str, Any]:
+    gl = sources["gitlab"]
+    return {
+        "project_id": gl["project_id"],
+        "updated_after": gl.get("updated_after", ""),
+        "target_branch": gl.get("target_branch", "main"),
+        "per_page": 10,
+        **_gl_creds(gl),
+    }
+
+
+def _list_gitlab_mrs_available(sources: dict[str, dict]) -> bool:
+    gl = sources.get("gitlab", {})
+    return bool(_gitlab_available(sources) and gl.get("project_id"))
+
+
+@tool(
+    name="list_gitlab_mrs",
+    source="gitlab",
+    description="List recent merge requests for a GitLab project.",
+    use_cases=[
+        "Checking whether a recently merged MR introduced a failure",
+        "Correlating an incident window with recent code merges to the target branch",
+        "Identifying open MRs that may have deployed breaking changes",
+    ],
+    requires=["project_id"],
+    surfaces=("investigation", "chat"),
+    input_schema={
+        "type": "object",
+        "properties": {
+            "project_id": {"type": "string"},
+            "target_branch": {"type": "string", "default": "main"},
+            "updated_after": {"type": "string"},
+            "per_page": {"type": "integer", "default": 10},
+            "gitlab_url": {"type": "string"},
+            "gitlab_token": {"type": "string"},
+        },
+        "required": ["project_id"],
+    },
+    is_available=_list_gitlab_mrs_available,
+    extract_params=_list_gitlab_mrs_extract_params,
+)
+def list_gitlab_mrs(
+    project_id: str,
+    target_branch: str = "main",
+    updated_after: str = "",
+    per_page: int = 10,
+    gitlab_url: str | None = None,
+    gitlab_token: str | None = None,
+    **_kwargs: Any,
+) -> dict[str, Any]:
+    """List recent merge requests for a GitLab project."""
+    config = _resolve_config(gitlab_url, gitlab_token)
+    if config is None:
+        return {
+            "source": "gitlab",
+            "available": False,
+            "error": "gitlab integration is not configured.",
+            "mrs": [],
+        }
+
+    result = get_gitlab_mrs(
+        config=config,
+        project_id=project_id,
+        target_branch=target_branch,
+        updated_after=updated_after,
+        per_page=per_page,
+    )
+    return {"source": "gitlab", "available": True, "mrs": result}

integrations/gitlab/tools/gitlab_pipelines_tool/__init__.py

@@ -0,0 +1,90 @@
+"""gitlab repository investigation tools."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from core.tool_framework.tool_decorator import tool
+from integrations.gitlab import (
+    get_gitlab_pipelines,
+)
+from integrations.gitlab.tools.gitlab_commits_tool import (
+    _gitlab_available,
+    _gl_creds,
+    _resolve_config,
+)
+
+
+def _list_gitlab_pipelines_extract_params(sources: dict[str, dict]) -> dict[str, Any]:
+    gl = sources["gitlab"]
+    return {
+        "project_id": gl["project_id"],
+        "updated_after": gl.get("updated_after", ""),
+        "ref": gl.get("ref_name", "main"),
+        "status": "failed",
+        "per_page": 10,
+        **_gl_creds(gl),
+    }
+
+
+def _list_gitlab_pipelines_available(sources: dict[str, dict]) -> bool:
+    gl = sources.get("gitlab", {})
+    return bool(_gitlab_available(sources) and gl.get("project_id"))
+
+
+@tool(
+    name="list_gitlab_pipelines",
+    source="gitlab",
+    description="List recent CI/CD pipelines for a GitLab project.",
+    use_cases=[
+        "Checking whether a failed pipeline caused or coincided with the incident",
+        "Correlating a deployment window with a pipeline that ran around the alert time",
+        "Identifying which CI job failed and on which branch",
+    ],
+    requires=["project_id"],
+    surfaces=("investigation", "chat"),
+    input_schema={
+        "type": "object",
+        "properties": {
+            "project_id": {"type": "string"},
+            "ref": {"type": "string", "default": "main"},
+            "updated_after": {"type": "string"},
+            "status": {"type": "string", "default": "failed"},
+            "per_page": {"type": "integer", "default": 10},
+            "gitlab_url": {"type": "string"},
+            "gitlab_token": {"type": "string"},
+        },
+        "required": ["project_id"],
+    },
+    is_available=_list_gitlab_pipelines_available,
+    extract_params=_list_gitlab_pipelines_extract_params,
+)
+def list_gitlab_pipelines(
+    project_id: str,
+    ref: str = "main",
+    updated_after: str = "",
+    status: str = "failed",
+    per_page: int = 10,
+    gitlab_url: str | None = None,
+    gitlab_token: str | None = None,
+    **_kwargs: Any,
+) -> dict[str, Any]:
+    """List recent CI/CD pipelines for a GitLab project."""
+    config = _resolve_config(gitlab_url, gitlab_token)
+    if config is None:
+        return {
+            "source": "gitlab",
+            "available": False,
+            "error": "gitlab integration is not configured.",
+            "pipelines": [],
+        }
+
+    result = get_gitlab_pipelines(
+        config=config,
+        project_id=project_id,
+        ref=ref,
+        status=status,
+        updated_after=updated_after,
+        per_page=per_page,
+    )
+    return {"source": "gitlab", "available": True, "pipelines": result}

integrations/gitlab/verifier.py

@@ -0,0 +1,12 @@
+"""GitLab integration verifier."""
+
+from __future__ import annotations
+
+from integrations.gitlab import build_gitlab_config, validate_gitlab_config
+from integrations.verification import register_validation_verifier
+
+verify_gitlab = register_validation_verifier(
+    "gitlab",
+    build_config=build_gitlab_config,
+    validate_config=validate_gitlab_config,
+)