commit-check · shenxianpeng · Jan 31, 2026 · Jan 31, 2026 · Jan 31, 2026 · Jan 31, 2026
@@ -80,7 +80,7 @@ Use Default Configuration
 Use Custom Configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-To customize the behavior, create a configuration file named ``cchk.toml`` or ``commit-check.toml`` in your repository's root directory, e.g., `cchk.toml <https://github.com/commit-check/commit-check/blob/main/cchk.toml>`_
+To customize the behavior, create a configuration file named ``cchk.toml`` or ``commit-check.toml`` in your repository's root directory or in the ``.github`` folder, e.g., `cchk.toml <https://github.com/commit-check/commit-check/blob/main/cchk.toml>`_ or ``.github/cchk.toml``.
 
 Usage
 -----

@@ -15,6 +15,8 @@
 DEFAULT_CONFIG_PATHS = [
     Path("cchk.toml"),
     Path("commit-check.toml"),
+    Path(".github/cchk.toml"),
+    Path(".github/commit-check.toml"),
 ]
 
 

@@ -43,7 +43,7 @@ def _get_parser() -> argparse.ArgumentParser:
     parser.add_argument(
         "-c",
         "--config",
-        help="path to config file (cchk.toml or commit-check.toml). If not specified, searches for cchk.toml in current directory",
+        help="path to config file (cchk.toml or commit-check.toml). If not specified, searches for config in: cchk.toml, commit-check.toml, .github/cchk.toml, .github/commit-check.toml",
     )
 
     parser.add_argument(

@@ -164,13 +164,18 @@ def _load_toml(path: PurePath) -> Dict[str, Any]:
 def _find_config_file(path_hint: str) -> Optional[PurePath]:
     """Resolve config file.
 
-    - If a directory is passed, search in priority: commit-check.toml, cchk.toml
+    - If a directory is passed, search in priority: cchk.toml, commit-check.toml, .github/cchk.toml, .github/commit-check.toml
     - If a file ending with .toml is passed, use it if exists.
     - Ignore legacy .commit-check.yml entirely.
     """
     p = Path(path_hint)
     if p.is_dir():
-        for name in ("commit-check.toml", "cchk.toml"):
+        for name in (
+            "cchk.toml",
+            "commit-check.toml",
+            ".github/cchk.toml",
+            ".github/commit-check.toml",
+        ):
             candidate = p / name
             if candidate.exists():
                 return candidate

@@ -14,7 +14,22 @@ Configuration
 
 commit-check can be configured via a ``cchk.toml`` or ``commit-check.toml`` file.
 
-The file should be placed in the root of your repository.
+The file should be placed in the root of your repository or in the ``.github`` folder.
+
+Configuration File Locations
+-----------------------------
+
+commit-check searches for configuration files in the following order (first found is used):
+
+1. ``cchk.toml`` (root directory)
+2. ``commit-check.toml`` (root directory)
+3. ``.github/cchk.toml``
+4. ``.github/commit-check.toml``
+
+.. tip::
+  **GitHub Best Practice**
+
+  Placing configuration files in the ``.github`` folder helps keep your repository root clean and follows GitHub conventions used by tools like Dependabot and Renovate.
 
 Example Configuration
 ---------------------

@@ -153,7 +153,7 @@ Common Issues
 
 **Issue**: "Configuration file not found"
 
-**Solution**: Ensure your file is named ``cchk.toml`` or ``commit-check.toml`` and placed in the repository root.
+**Solution**: Ensure your file is named ``cchk.toml`` or ``commit-check.toml`` and placed in the repository root or in the ``.github`` folder.
 
 **Issue**: "Invalid TOML syntax"
 

@@ -79,6 +79,79 @@ def test_load_config_default_commit_check_toml(self):
             finally:
                 os.chdir(original_cwd)
 
+    @pytest.mark.benchmark
+    def test_load_config_github_cchk_toml(self):
+        """Test loading config from .github/cchk.toml path."""
+        config_content = b"""
+[checks]
+github_cchk = true
+"""
+        original_cwd = os.getcwd()
+        with tempfile.TemporaryDirectory() as tmpdir:
+            os.chdir(tmpdir)
+            try:
+                # Create .github directory
+                os.makedirs(".github", exist_ok=True)
+                with open(".github/cchk.toml", "wb") as f:
+                    f.write(config_content)
+
+                config = load_config()
+                assert "checks" in config
+                assert config["checks"]["github_cchk"] is True
+            finally:
+                os.chdir(original_cwd)
+
+    @pytest.mark.benchmark
+    def test_load_config_github_commit_check_toml(self):
+        """Test loading config from .github/commit-check.toml path."""
+        config_content = b"""
+[checks]
+github_commit_check = true
+"""
+        original_cwd = os.getcwd()
+        with tempfile.TemporaryDirectory() as tmpdir:
+            os.chdir(tmpdir)
+            try:
+                # Create .github directory
+                os.makedirs(".github", exist_ok=True)
+                with open(".github/commit-check.toml", "wb") as f:
+                    f.write(config_content)
+
+                config = load_config()
+                assert "checks" in config
+                assert config["checks"]["github_commit_check"] is True
+            finally:
+                os.chdir(original_cwd)
+
+    @pytest.mark.benchmark
+    def test_load_config_priority_root_over_github(self):
+        """Test that root config files have priority over .github folder."""
+        root_config = b"""
+[checks]
+location = "root"
+"""
+        github_config = b"""
+[checks]
+location = "github"
+"""
+        original_cwd = os.getcwd()
+        with tempfile.TemporaryDirectory() as tmpdir:
+            os.chdir(tmpdir)
+            try:
+                # Create both root and .github configs
+                with open("cchk.toml", "wb") as f:
+                    f.write(root_config)
+                os.makedirs(".github", exist_ok=True)
+                with open(".github/cchk.toml", "wb") as f:
+                    f.write(github_config)
+
+                config = load_config()
+                assert "checks" in config
+                # Should load from root, not .github
+                assert config["checks"]["location"] == "root"
+            finally:
+                os.chdir(original_cwd)
+
     @pytest.mark.benchmark
     def test_load_config_file_not_found(self):
         """Test returning empty config when no default config files exist."""
@@ -110,9 +183,11 @@ def test_load_config_file_not_found_with_invalid_path_hint(self):
     @pytest.mark.benchmark
     def test_default_config_paths_constant(self):
         """Test that DEFAULT_CONFIG_PATHS contains expected paths."""
-        assert len(DEFAULT_CONFIG_PATHS) == 2
+        assert len(DEFAULT_CONFIG_PATHS) == 4
         assert Path("cchk.toml") in DEFAULT_CONFIG_PATHS
         assert Path("commit-check.toml") in DEFAULT_CONFIG_PATHS
+        assert Path(".github/cchk.toml") in DEFAULT_CONFIG_PATHS
+        assert Path(".github/commit-check.toml") in DEFAULT_CONFIG_PATHS
 
     @pytest.mark.benchmark
     def test_toml_load_function_exists(self):

@@ -428,16 +428,54 @@ def test_find_config_file_directory_cchk_toml(self):
                 assert result == config_file
 
         def test_find_config_file_directory_priority(self):
-            """Test _find_config_file prefers commit-check.toml over cchk.toml."""
+            """Test _find_config_file prefers cchk.toml over commit-check.toml."""
             with tempfile.TemporaryDirectory() as tmpdir:
-                config1 = Path(tmpdir) / "commit-check.toml"
-                config2 = Path(tmpdir) / "cchk.toml"
+                config1 = Path(tmpdir) / "cchk.toml"
+                config2 = Path(tmpdir) / "commit-check.toml"
                 config1.write_text("[checks]")
                 config2.write_text("[checks]")
 
                 result = _find_config_file(tmpdir)
                 assert result == config1
 
+        def test_find_config_file_github_directory_cchk_toml(self):
+            """Test _find_config_file finds .github/cchk.toml in directory."""
+            with tempfile.TemporaryDirectory() as tmpdir:
+                github_dir = Path(tmpdir) / ".github"
+                github_dir.mkdir()
+                config_file = github_dir / "cchk.toml"
+                config_file.write_text("[checks]")
+
+                result = _find_config_file(tmpdir)
+                assert result == config_file
+
+        def test_find_config_file_github_directory_commit_check_toml(self):
+            """Test _find_config_file finds .github/commit-check.toml in directory."""
+            with tempfile.TemporaryDirectory() as tmpdir:
+                github_dir = Path(tmpdir) / ".github"
+                github_dir.mkdir()
+                config_file = github_dir / "commit-check.toml"
+                config_file.write_text("[checks]")
+
+                result = _find_config_file(tmpdir)
+                assert result == config_file
+
+        def test_find_config_file_priority_root_over_github(self):
+            """Test _find_config_file prefers root configs over .github configs."""
+            with tempfile.TemporaryDirectory() as tmpdir:
+                # Create both root and .github configs
+                root_config = Path(tmpdir) / "cchk.toml"
+                root_config.write_text("[checks]")
+
+                github_dir = Path(tmpdir) / ".github"
+                github_dir.mkdir()
+                github_config = github_dir / "cchk.toml"
+                github_config.write_text("[checks]")
+
+                result = _find_config_file(tmpdir)
+                # Should prefer root over .github
+                assert result == root_config
+
         def test_find_config_file_directory_no_config(self):
             """Test _find_config_file returns None when no config found in directory."""
             with tempfile.TemporaryDirectory() as tmpdir: