feat(ci): auto-detect Mergify config file path (#922)

Add get_mergify_config_path() helper that looks for the config file in
multiple locations (.mergify.yml, .mergify/config.yml, .github/mergify.yml)
and returns None if no config file is found. The scopes command now
raises a clear error message listing all checked locations when no
config file exists.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: sileht

mergify_cli/ci/cli.py

@@ -212,9 +212,8 @@ def git_refs() -> None:
 @click.option(
     "--config",
     "config_path",
-    required=True,
-    type=click.Path(exists=True),
-    default=".mergify.yml",
+    type=click.Path(),
+    default=detector.get_mergify_config_path,
     help="Path to YAML config file.",
 )
 @click.option(
@@ -232,11 +231,16 @@ def git_refs() -> None:
     help="Write the detected scopes to a file (json).",
 )
 def scopes(
-    config_path: str,
+    config_path: str | None,
     write: str | None = None,
     head: str | None = None,
     base: str | None = None,
 ) -> None:
+    if config_path is None:
+        locations = ", ".join(detector.MERGIFY_CONFIG_PATHS)
+        msg = f"Mergify configuration file not found. Looked in: {locations}"
+        raise click.ClickException(msg)
+
     if base or head:
         ref = git_refs_detector.References(
             base=base,

mergify_cli/ci/detector.py

@@ -202,3 +202,26 @@ def get_github_repository() -> str | None:
             return _get_github_repository_from_env("GIT_URL")
         case _:
             return None
+
+
+MERGIFY_CONFIG_PATHS = (
+    ".mergify.yml",
+    ".mergify/config.yml",
+    ".github/mergify.yml",
+)
+
+
+def get_mergify_config_path() -> str | None:
+    """Detect the Mergify configuration file path.
+
+    Looks for the config file in these locations in order:
+    - .mergify.yml
+    - .mergify/config.yml
+    - .github/mergify.yml
+
+    Returns None if no config file is found.
+    """
+    for config_path in MERGIFY_CONFIG_PATHS:
+        if pathlib.Path(config_path).is_file():
+            return config_path
+    return None

mergify_cli/tests/ci/test_detector.py

@@ -163,3 +163,65 @@ def test_get_github_pull_request_number_unsupported_ci(
 
     result = detector.get_github_pull_request_number()
     assert result is None
+
+
+def test_get_mergify_config_path_default_file(
+    tmp_path: pathlib.Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / ".mergify.yml").touch()
+
+    result = detector.get_mergify_config_path()
+    assert result == ".mergify.yml"
+
+
+def test_get_mergify_config_path_mergify_dir(
+    tmp_path: pathlib.Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / ".mergify").mkdir()
+    (tmp_path / ".mergify" / "config.yml").touch()
+
+    result = detector.get_mergify_config_path()
+    assert result == ".mergify/config.yml"
+
+
+def test_get_mergify_config_path_github_dir(
+    tmp_path: pathlib.Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / ".github").mkdir()
+    (tmp_path / ".github" / "mergify.yml").touch()
+
+    result = detector.get_mergify_config_path()
+    assert result == ".github/mergify.yml"
+
+
+def test_get_mergify_config_path_priority(
+    tmp_path: pathlib.Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Test that .mergify.yml takes priority over other locations."""
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / ".mergify.yml").touch()
+    (tmp_path / ".mergify").mkdir()
+    (tmp_path / ".mergify" / "config.yml").touch()
+    (tmp_path / ".github").mkdir()
+    (tmp_path / ".github" / "mergify.yml").touch()
+
+    result = detector.get_mergify_config_path()
+    assert result == ".mergify.yml"
+
+
+def test_get_mergify_config_path_none_when_missing(
+    tmp_path: pathlib.Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Test that None is returned when no config file exists."""
+    monkeypatch.chdir(tmp_path)
+
+    result = detector.get_mergify_config_path()
+    assert result is None