feat(git-hooks): set repo remote fallback with env variable

In some configurations ggshield runs in repositories without a configured remote, for example when running in a git pre-receive hook. This commit adds a REPOSITORY_REMOTE_FALLBACK environment variable for setting a fallback value for the remote URL.

Issue #1158

Author: Kevin Westphal

.env.example

@@ -16,3 +16,7 @@ GITGUARDIAN_INSTANCE=https://dashboard.gitguardian.com/
 # - and set TEST_GG_VALID_TOKEN_IGNORE_SHA to matching commit sha
 # TEST_GG_VALID_TOKEN=
 # TEST_GG_VALID_TOKEN_IGNORE_SHA=
+
+# Fallback value for the repository remote URL in case it cannot be determined using `git remote -v`
+# This variable is particularly relevant when running ggshield in a git pre-receive hook
+#REPOSITORY_REMOTE_FALLBACK=

changelog.d/20251210_173258_kevin.westphal_set_repo_url_in_env_var.md

@@ -0,0 +1,42 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+For top level release notes, leave all the headers commented out.
+-->
+
+<!--
+### Removed
+
+- A bullet item for the Removed category.
+
+-->
+
+### Added
+
+- Add `REPOSITORY_REMOTE_FALLBACK` environment variable that allows setting a fallback value for the repository remote.
+
+<!--
+### Changed
+
+- A bullet item for the Changed category.
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category.
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category.
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category.
+
+-->

ggshield/core/env_utils.py

@@ -14,6 +14,7 @@
     "GITGUARDIAN_INSTANCE",
     "GITGUARDIAN_API_URL",
     "GITGUARDIAN_API_KEY",
+    "REPOSITORY_REMOTE_FALLBACK",
 }
 
 logger = logging.getLogger(__name__)

ggshield/utils/git_shell.py

@@ -379,21 +379,39 @@ def get_repository_url_from_path(wd: Path) -> Optional[str]:
     Returns one of the repository remote urls. Returns None if no remote are found,
     or the directory is not a repository or we don't have git so we can't know if the
     directory is a repository.
+
+    If REPOSITORY_REMOTE_FALLBACK environment variable is set, it will be used as a
+    fallback value when no remote URL can be detected from the git repository.
     """
     try:
         if not is_git_available() or not is_git_dir(wd):
-            return None
+            return _get_repository_url_fallback()
         remotes_raw = git(["remote", "-v"], cwd=wd).splitlines()
     except (subprocess.CalledProcessError, OSError):
-        return None
+        return _get_repository_url_fallback()
 
     url: Optional[str] = None
     for line in remotes_raw:
         if match := re.search(r"^(.*)\t(.*) \(fetch\)$", line):
             name, url = match.groups()
             if name == "origin":
                 break
-    return simplify_git_url(url) if url else None
+
+    if url:
+        return simplify_git_url(url)
+
+    return _get_repository_url_fallback()
+
+
+def _get_repository_url_fallback() -> Optional[str]:
+    """
+    Returns the repository URL from the REPOSITORY_REMOTE_FALLBACK environment variable.
+    Returns None if the environment variable is not set or empty.
+    """
+    url = os.getenv("REPOSITORY_REMOTE_FALLBACK")
+    if url:
+        return simplify_git_url(url)
+    return None
 
 
 def get_filepaths_from_ref(

tests/unit/cmd/scan/test_path.py

@@ -557,3 +557,47 @@ def test_scan_context_repository(
             and arg.get("GGShield-Repository-URL") == "github.com/owner/repository"
             for arg in scan_mock.call_args[0]
         )
+
+    @patch("pygitguardian.GGClient.multi_content_scan")
+    @my_vcr.use_cassette("test_scan_context_repository.yaml")
+    def test_scan_path_with_fallback_repository_url(
+        self,
+        scan_mock: Mock,
+        tmp_path: Path,
+        cli_fs_runner: CliRunner,
+    ) -> None:
+        """
+        GIVEN a repository without a remote url
+        WHEN executing a scan with REPOSITORY_REMOTE_FALLBACK set
+        THEN the environment variable value is sent in the headers
+        """
+        local_repo = Repository.create(tmp_path)
+
+        file = local_repo.path / "file_secret"
+        write_text(file, "Hello")
+        local_repo.add(file)
+        local_repo.create_commit()
+
+        scan_result = MultiScanResult([])
+        scan_result.status_code = 200
+        scan_mock.return_value = scan_result
+
+        fallback_url = "https://github.com/fallback/repository.git"
+        with patch.dict(os.environ, {"REPOSITORY_REMOTE_FALLBACK": fallback_url}):
+            result = cli_fs_runner.invoke(
+                cli,
+                [
+                    "secret",
+                    "scan",
+                    "path",
+                    str(file),
+                ],
+            )
+        assert result.exit_code == ExitCode.SUCCESS, result.output
+
+        scan_mock.assert_called_once()
+        assert any(
+            isinstance(arg, dict)
+            and arg.get("GGShield-Repository-URL") == "github.com/fallback/repository"
+            for arg in scan_mock.call_args[0]
+        )

tests/unit/core/scan/test_scan_context.py

@@ -123,3 +123,57 @@ def test_ci_no_env(env, fake_url_repo: Repository) -> None:
             target_path=fake_url_repo.path,
         )
         _assert_repo_url_in_headers(context, EXPECTED_HEADER_REMOTE)
+
+
+def test_fallback_env_var_used_when_no_remote(tmp_path: Path) -> None:
+    """
+    GIVEN a repository without a remote
+    WHEN REPOSITORY_REMOTE_FALLBACK is set
+    THEN the environment variable value is used in the headers
+    """
+    # Create a repository without a remote
+    repo = Repository.create(tmp_path / "repo")
+    repo.create_commit()
+
+    fallback_url = "https://github.com/fallback/repository.git"
+    with mock.patch.dict(os.environ, {"REPOSITORY_REMOTE_FALLBACK": fallback_url}):
+        context = ScanContext(
+            scan_mode=ScanMode.PATH,
+            command_path="ggshield secret scan path",
+            target_path=repo.path,
+        )
+        _assert_repo_url_in_headers(context, "github.com/fallback/repository")
+
+
+def test_fallback_env_var_not_used_when_remote_exists(
+    fake_url_repo: Repository,
+) -> None:
+    """
+    GIVEN a repository with a remote
+    WHEN REPOSITORY_REMOTE_FALLBACK is set
+    THEN the remote URL takes precedence over the environment variable
+    """
+    fallback_url = "https://github.com/fallback/repository.git"
+    with mock.patch.dict(os.environ, {"REPOSITORY_REMOTE_FALLBACK": fallback_url}):
+        context = ScanContext(
+            scan_mode=ScanMode.PATH,
+            command_path="ggshield secret scan path",
+            target_path=fake_url_repo.path,
+        )
+        _assert_repo_url_in_headers(context, EXPECTED_HEADER_REMOTE)
+
+
+def test_fallback_env_var_used_when_not_git_dir(tmp_path: Path) -> None:
+    """
+    GIVEN a directory which is not a git repository
+    WHEN REPOSITORY_REMOTE_FALLBACK is set
+    THEN the environment variable value is used in the headers
+    """
+    fallback_url = "https://github.com/fallback/repository.git"
+    with mock.patch.dict(os.environ, {"REPOSITORY_REMOTE_FALLBACK": fallback_url}):
+        context = ScanContext(
+            scan_mode=ScanMode.PATH,
+            command_path="ggshield secret scan path",
+            target_path=tmp_path,
+        )
+        _assert_repo_url_in_headers(context, "github.com/fallback/repository")

tests/unit/utils/test_git_shell.py

@@ -292,6 +292,85 @@ def test_get_repository_url_from_path_subrepo(tmp_path: Path):
     assert "repository2" in get_repository_url_from_path(local_repo2.path)
 
 
+def test_get_repository_url_from_path_with_env_var_fallback(tmp_path: Path):
+    # GIVEN a repository without a remote
+    local_repository_path = tmp_path / "repo"
+    repo = Repository.create(local_repository_path)
+    repo.create_commit()
+
+    # AND a REPOSITORY_REMOTE_FALLBACK environment variable set
+    fallback_url = "https://github.com/fallback/repository.git"
+    with patch.dict(os.environ, {"REPOSITORY_REMOTE_FALLBACK": fallback_url}):
+        # WHEN getting the repository URL
+        url = get_repository_url_from_path(local_repository_path)
+
+        # THEN the fallback URL is returned and simplified
+        assert url == "github.com/fallback/repository"
+
+
+def test_get_repository_url_from_path_env_var_not_used_when_remote_exists(
+    tmp_path: Path,
+):
+    # GIVEN a repository with a remote
+    local_repo = _create_repository_with_remote(tmp_path, "repository")
+
+    # AND a REPOSITORY_REMOTE_FALLBACK environment variable set
+    fallback_url = "https://github.com/fallback/repository.git"
+    with patch.dict(os.environ, {"REPOSITORY_REMOTE_FALLBACK": fallback_url}):
+        # WHEN getting the repository URL
+        url = get_repository_url_from_path(local_repo.path)
+
+        # THEN the remote URL is returned, not the fallback
+        assert "repository" in url
+        assert "fallback" not in url
+
+
+def test_get_repository_url_from_path_env_var_with_non_git_dir(tmp_path: Path):
+    # GIVEN a local directory with no git repository
+    local_directory_path = tmp_path / "local"
+    local_directory_path.mkdir()
+
+    # AND a REPOSITORY_REMOTE_FALLBACK environment variable set
+    fallback_url = "https://github.com/fallback/repository.git"
+    with patch.dict(os.environ, {"REPOSITORY_REMOTE_FALLBACK": fallback_url}):
+        # WHEN getting the repository URL
+        url = get_repository_url_from_path(local_directory_path)
+
+        # THEN the fallback URL is returned
+        assert url == "github.com/fallback/repository"
+
+
+def test_get_repository_url_from_path_env_var_empty(tmp_path: Path):
+    # GIVEN a repository without a remote
+    local_repository_path = tmp_path / "repo"
+    repo = Repository.create(local_repository_path)
+    repo.create_commit()
+
+    # AND an empty REPOSITORY_REMOTE_FALLBACK environment variable
+    with patch.dict(os.environ, {"REPOSITORY_REMOTE_FALLBACK": ""}):
+        # WHEN getting the repository URL
+        url = get_repository_url_from_path(local_repository_path)
+
+        # THEN no URL is returned
+        assert url is None
+
+
+def test_get_repository_url_from_path_env_var_simplifies_url(tmp_path: Path):
+    # GIVEN a repository without a remote
+    local_repository_path = tmp_path / "repo"
+    repo = Repository.create(local_repository_path)
+    repo.create_commit()
+
+    # AND a REPOSITORY_REMOTE_FALLBACK environment variable with a complex URL
+    fallback_url = "https://user:[email protected]:84/owner/repo.git"
+    with patch.dict(os.environ, {"REPOSITORY_REMOTE_FALLBACK": fallback_url}):
+        # WHEN getting the repository URL
+        url = get_repository_url_from_path(local_repository_path)
+
+        # THEN the URL is simplified
+        assert url == "github.com/owner/repo"
+
+
 def test_get_filepaths_from_ref(tmp_path):
     # GIVEN a repository
     repo = Repository.create(tmp_path)