Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(git): support git@ SSH URLs with regression-safe repo detection (#317) (#385)

r266-tech6aa8e7db2bde
diff --git a/openviking/parse/parsers/code/code.py b/openviking/parse/parsers/code/code.py
index de7580ec0..b59fed700 100644
--- a/openviking/parse/parsers/code/code.py
+++ b/openviking/parse/parsers/code/code.py
@@ -111,7 +111,15 @@ class CodeRepositoryParser(BaseParser):
# 2. Fetch content (Clone or Extract)
repo_name = "repository"
local_dir = Path(temp_local_dir)
- if source_str.startswith(("http://", "https://", "git://", "ssh://")):
+ if source_str.startswith("git@"):
+ # git@ SSH URL: use git clone directly (no GitHub ZIP optimization)
+ repo_name = await self._git_clone(
+ source_str,
+ temp_local_dir,
+ branch=branch,
+ commit=commit,
+ )
+ elif source_str.startswith(("http://", "https://", "git://", "ssh://")):
repo_url, branch, commit = self._parse_repo_source(source_str, **kwargs)
if self._is_github_url(repo_url) and not commit:
# Use GitHub ZIP API: single HTTPS download, no git history, much faster
@@ -292,7 +300,14 @@ class CodeRepositoryParser(BaseParser):
stdout, stderr = await proc.communicate()
if proc.returncode != 0:
error_msg = stderr.decode().strip()
- raise RuntimeError(f"Git command failed: {' '.join(args)}: {error_msg}")
+ user_msg = "Git command failed."
+ if "Could not resolve hostname" in error_msg:
+ user_msg = "Git command failed: could not resolve hostname. Check the URL or your network."
+ elif "Permission denied" in error_msg or "publickey" in error_msg:
+ user_msg = "Git command failed: authentication error. Check your SSH keys or credentials."
+ raise RuntimeError(
+ f'{user_msg} Command: git {" ".join(args[1:])}. Details: {error_msg}'
+ )
return stdout.decode().strip()
async def _has_commit(self, repo_dir: str, commit: str) -> bool:
diff --git a/openviking/utils/__init__.py b/openviking/utils/__init__.py
index be6def670..2ca0b3884 100644
--- a/openviking/utils/__init__.py
+++ b/openviking/utils/__init__.py
@@ -4,9 +4,11 @@
from openviking.utils.code_hosting_utils import (
is_code_hosting_url,
+ is_git_repo_url,
is_github_url,
is_gitlab_url,
parse_code_hosting_url,
+ validate_git_ssh_uri,
)
from openviking.utils.time_utils import get_current_timestamp
from openviking_cli.utils.async_utils import run_async
@@ -27,4 +29,6 @@ __all__ = [
"is_github_url",
"is_gitlab_url",
"is_code_hosting_url",
+ "validate_git_ssh_uri",
+ "is_git_repo_url",
]
diff --git a/openviking/utils/code_hosting_utils.py b/openviking/utils/code_hosting_utils.py
index eab27a2a2..e97ddae3d 100644
--- a/openviking/utils/code_hosting_utils.py
+++ b/openviking/utils/code_hosting_utils.py
@@ -18,19 +18,46 @@ def parse_code_hosting_url(url: str) -> Optional[str]:
Args:
url: Code hosting URL like https://github.com/volcengine/OpenViking
+ or [email protected]:volcengine/OpenViking.git
Returns:
org/repo path like "volcengine/OpenViking" or None if not a valid
code hosting URL
"""
+ config = get_openviking_config()
+ all_domains = list(
+ set(
+ config.code.github_domains
+ + config.code.gitlab_domains
+ + config.code.code_hosting_domains
+ )
+ )
+
+ # Handle git@ SSH URLs: git@host:org/repo.git
+ if url.startswith("git@"):
+ if ":" not in url[4:]:
+ return None
+ host_part, path_part = url[4:].split(":", 1)
+ if host_part not in all_domains:
+ return None
+ path_parts = [p for p in path_part.split("/") if p]
+ if len(path_parts) < 2:
+ return None
+ # Take only first 2 segments (consistent with HTTP branch)
+ org = path_parts[0]
+ repo = path_parts[1]
+ if repo.endswith(".git"):
+ repo = repo[:-4]
+ org = "".join(c if c.isalnum() or c in "-_" else "_" for c in org)
+ repo = "".join(c if c.isalnum() or c in "-_" else "_" for c in repo)
+ return f"{org}/{repo}"
+
if not url.startswith(("http://", "https://", "git://", "ssh://")):
return None
parsed = urlparse(url)
path_parts = [p for p in parsed.path.split("/") if p]
- config = get_openviking_config()
-
# For GitHub/GitLab URLs with org/repo structure
if (
parsed.netloc in config.code.github_domains + config.code.gitlab_domains
@@ -92,4 +119,66 @@ def is_code_hosting_url(url: str) -> bool:
+ config.code.code_hosting_domains
)
)
+
+ # Handle git@ SSH URLs
+ if url.startswith("git@"):
+ if ":" not in url[4:]:
+ return False
+ host_part = url[4:].split(":", 1)[0]
+ return host_part in all_domains
+
return urlparse(url).netloc in all_domains
+
+
+def validate_git_ssh_uri(url: str) -> None:
+ """Validate a git@ SSH URI format.
+
+ Args:
+ url: URL to validate (e.g. [email protected]:org/repo.git)
+
+ Raises:
+ ValueError: If the URL is not a valid git@ SSH URI
+ """
+ if not url.startswith("git@"):
+ raise ValueError(f"Not a git@ SSH URI: {url}")
+ rest = url[4:]
+ if ":" not in rest or not rest.split(":", 1)[1]:
+ raise ValueError(f"Invalid git@ SSH URI (missing colon or empty path): {url}")
+
+
+def is_git_repo_url(url: str) -> bool:
+ """Strict check for cloneable git repository URLs.
+
+ Distinguishes repo URLs (github.com/org/repo) from non-repo URLs
+ (github.com/org/repo/issues/123).
+
+ Args:
+ url: URL to check
+
+ Returns:
+ True if the URL points to a cloneable git repository
+ """
+ # git@/ssh://git:// protocols: always a repo if the domain matches
+ if url.startswith(("git@", "ssh://", "git://")):
+ return is_code_hosting_url(url)
+
+ # http/https: check domain AND require exactly 2 path parts (owner/repo)
+ if url.startswith(("http://", "https://")):
+ config = get_openviking_config()
+ all_domains = list(
+ set(
+ config.code.github_domains
+ + config.code.gitlab_domains
+ + config.code.code_hosting_domains
+ )
+ )
+ parsed = urlparse(url)
+ if parsed.netloc not in all_domains:
+ return False
+ path_parts = [p for p in parsed.path.split("/") if p]
+ # Strip .git suffix from last part for counting
+ if path_parts and path_parts[-1].endswith(".git"):
+ path_parts[-1] = path_parts[-1][:-4]
+ return len(path_parts) == 2
+
+ return False
diff --git a/openviking/utils/media_processor.py b/openviking/utils/media_processor.py
index 2edc005c1..b89525afb 100644
--- a/openviking/utils/media_processor.py
+++ b/openviking/utils/media_processor.py
@@ -70,10 +70,23 @@ class UnifiedResourceProcessor:
def _is_url(self, source: str) -> bool:
"""Check if source is a URL."""
- return source.startswith(("http://", "https://"))
+ return source.startswith(("http://", "https://", "git@", "ssh://", "git://"))
- async def _process_url(self, url: str, instruction: str) -> ParseResult:
+ async def _process_url(self, url: str, instruction: str, **kwargs) -> ParseResult:
"""Process URL source."""
+ from openviking.utils.code_hosting_utils import is_git_repo_url, validate_git_ssh_uri
+
+ # Validate git@ SSH URIs early
+ if url.startswith("git@"):
+ validate_git_ssh_uri(url)
+
+ # Route git protocols and repo URLs to CodeRepositoryParser
+ if url.startswith(("git@", "git://", "ssh://")) or is_git_repo_url(url):
+ from openviking.parse.parsers.code.code import CodeRepositoryParser
+
+ parser = CodeRepositoryParser()
+ return await parser.parse(url, instruction=instruction)
+
from openviking.parse.parsers.html import HTMLParser
parser = HTMLParser()
diff --git a/openviking_cli/cli/commands/resources.py b/openviking_cli/cli/commands/resources.py
index 4324ad6ca..6fafbb189 100644
--- a/openviking_cli/cli/commands/resources.py
+++ b/openviking_cli/cli/commands/resources.py
@@ -41,7 +41,9 @@ def register(app: typer.Typer) -> None:
"""Add resources into OpenViking."""
# Validate path: if it's a local path, check if it exists
final_path = path
- if not (path.startswith("http://") or path.startswith("https://")):
+ if not (
+ path.startswith(("http://", "https://", "git@", "ssh://", "git://"))
+ ):
unescaped_path = path.replace("\\ ", " ")
local_path = Path(unescaped_path)
final_path = unescaped_path
diff --git a/tests/test_code_hosting_utils.py b/tests/test_code_hosting_utils.py
new file mode 100644
index 000000000..a12704570
--- /dev/null
+++ b/tests/test_code_hosting_utils.py
@@ -0,0 +1,147 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: Apache-2.0
+"""Tests for code_hosting_utils git SSH URL support (Issue #317)."""
+
+import importlib
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType, SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+
+
+def _mock_config():
+ return SimpleNamespace(
+ code=SimpleNamespace(
+ github_domains=["github.com", "www.github.com"],
+ gitlab_domains=["gitlab.com", "www.gitlab.com"],
+ code_hosting_domains=["github.com", "gitlab.com"],
+ )
+ )
+
+
+# Ensure openviking_cli.utils.config is importable (stub if needed)
+_config_mod_name = "openviking_cli.utils.config"
+try:
+ importlib.import_module(_config_mod_name)
+except Exception:
+ for mod_name in ("openviking_cli", "openviking_cli.utils", _config_mod_name):
+ if mod_name not in sys.modules:
+ m = ModuleType(mod_name)
+ sys.modules[mod_name] = m
+ sys.modules[_config_mod_name].get_openviking_config = _mock_config # type: ignore[attr-defined]
+
+# Load code_hosting_utils directly from file to avoid the heavy openviking/__init__.py chain
+_module_path = Path(__file__).resolve().parents[1] / "openviking" / "utils" / "code_hosting_utils.py"
+_spec = importlib.util.spec_from_file_location("openviking.utils.code_hosting_utils", _module_path)
+_module = importlib.util.module_from_spec(_spec)
+sys.modules["openviking.utils.code_hosting_utils"] = _module
+_spec.loader.exec_module(_module)
+
+parse_code_hosting_url = _module.parse_code_hosting_url
+is_code_hosting_url = _module.is_code_hosting_url
+is_git_repo_url = _module.is_git_repo_url
+validate_git_ssh_uri = _module.validate_git_ssh_uri
+
+
[email protected](autouse=True)
+def _patch_config():
+ with patch.object(_module, "get_openviking_config", side_effect=_mock_config):
+ yield
+
+
+# --- parse_code_hosting_url ---
+
+
+def test_parse_code_hosting_url_git_ssh():
+ assert parse_code_hosting_url("[email protected]:org/repo.git") == "org/repo"
+
+
+def test_parse_code_hosting_url_git_ssh_no_dotgit():
+ assert parse_code_hosting_url("[email protected]:org/repo") == "org/repo"
+
+
+def test_parse_code_hosting_url_git_ssh_unknown_host():
+ assert parse_code_hosting_url("[email protected]:org/repo.git") is None
+
+
+def test_parse_code_hosting_url_git_ssh_single_segment():
+ assert parse_code_hosting_url("[email protected]:repo") is None
+
+
+def test_parse_code_hosting_url_https():
+ assert parse_code_hosting_url("https://github.com/org/repo") == "org/repo"
+
+
+def test_parse_code_hosting_url_https_dotgit():
+ assert parse_code_hosting_url("https://github.com/org/repo.git") == "org/repo"
+
+
+# --- validate_git_ssh_uri ---
+
+
+def test_validate_git_ssh_uri_valid():
+ validate_git_ssh_uri("[email protected]:org/repo.git") # should not raise
+
+
+def test_validate_git_ssh_uri_not_git():
+ with pytest.raises(ValueError, match="Not a git@ SSH URI"):
+ validate_git_ssh_uri("https://github.com/org/repo")
+
+
+def test_validate_git_ssh_uri_no_colon():
+ with pytest.raises(ValueError, match="missing colon or empty path"):
+ validate_git_ssh_uri("[email protected]")
+
+
+def test_validate_git_ssh_uri_empty_path():
+ with pytest.raises(ValueError, match="missing colon or empty path"):
+ validate_git_ssh_uri("[email protected]:")
+
+
+# --- is_code_hosting_url ---
+
+
+def test_is_code_hosting_url_git_ssh():
+ assert is_code_hosting_url("[email protected]:org/repo.git") is True
+
+
+def test_is_code_hosting_url_git_ssh_no_colon():
+ assert is_code_hosting_url("[email protected]") is False
+
+
+def test_is_code_hosting_url_https():
+ assert is_code_hosting_url("https://github.com/org/repo") is True
+
+
+# --- is_git_repo_url ---
+
+
+def test_is_git_repo_url_git_ssh():
+ assert is_git_repo_url("[email protected]:org/repo.git") is True
+
+
+def test_is_git_repo_url_https_repo():
+ assert is_git_repo_url("https://github.com/org/repo") is True
+
+
+def test_is_git_repo_url_https_issues():
+ assert is_git_repo_url("https://github.com/org/repo/issues/123") is False
+
+
+def test_is_git_repo_url_https_pull():
+ assert is_git_repo_url("https://github.com/org/repo/pull/456") is False
+
+
+def test_is_git_repo_url_https_blob():
+ assert is_git_repo_url("https://github.com/org/repo/blob/main/file.py") is False
+
+
+def test_is_git_repo_url_unknown_domain():
+ assert is_git_repo_url("https://example.com/org/repo") is False
+
+
+def test_is_git_repo_url_single_segment():
+ assert is_git_repo_url("https://github.com/org") is False