feat: initial release of git-change-detection

Author: Kevin Allioli

.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install package
+        run: pip install -e .
+
+      - name: Verify CLI
+        run: git-change-detection --help
+
+  release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: test
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+*.lock

README.md

@@ -0,0 +1,66 @@
+# git-change-detection
+
+Detect which Ansible playbooks need to run based on git changes and metadata files.
+
+## Usage
+
+```bash
+git-change-detection <START_SHA> <END_SHA> \
+  --metadata ansible/inventory/prod/.metadata.yml \
+  --metadata ansible/playbooks/.metadata.yml \
+  --json
+```
+
+## Metadata format
+
+Create `.metadata.yml` files that map file glob patterns to playbook names:
+
+```yaml
+playbooks/setup-networking.yml:
+  stage: 1
+  depends_on: []
+  paths:
+    - "ansible/roles/networking/**"
+    - "ansible/inventory/*/group_vars/networking.yml"
+
+playbooks/setup-monitoring.yml:
+  stage: 2
+  depends_on:
+    - "playbooks/setup-networking.yml"
+  paths:
+    - "ansible/roles/monitoring/**"
+```
+
+## Output (JSON)
+
+```json
+{
+  "playbooks/setup-networking.yml": {
+    "triggered": true,
+    "stage": 1,
+    "depends_on": []
+  },
+  "playbooks/setup-monitoring.yml": {
+    "triggered": true,
+    "stage": 2,
+    "depends_on": ["playbooks/setup-networking.yml"]
+  }
+}
+```
+
+- **`triggered`**: `true` if any changed file matches the patterns, or if a dependency was triggered
+- **`stage`**: execution order (sorted by the CI)
+- **`depends_on`**: list of playbook names this depends on (triggers cascade)
+
+## Install
+
+```bash
+pip install git-change-detection
+```
+
+## Development
+
+```bash
+uv sync
+uv run git-change-detection --help
+```

pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "git-change-detection"
+version = "0.1.0"
+description = "Detect which Ansible playbooks need to run based on git changes and metadata files"
+readme = "README.md"
+requires-python = ">=3.13"
+license = {text = "MIT"}
+dependencies = [
+  "click>=8.1",
+  "jinja2>=3.1.6",
+  "pyyaml>=6.0",
+  "gitpython>=3.1",
+]
+
+[project.scripts]
+git-change-detection = "git_change_detection.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/git_change_detection"]

src/git_change_detection/__init__.py

@@ -0,0 +1,3 @@
+"""git-change-detection: Detect which Ansible playbooks to run based on git diff and metadata."""
+
+__version__ = "0.1.0"

src/git_change_detection/cli.py

@@ -0,0 +1,79 @@
+"""CLI entry point for git-change-detection."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+import yaml
+
+from git_change_detection.detector import detect_changes
+
+
+@click.command()
+@click.argument("start")
+@click.argument("end")
+@click.option(
+    "--metadata",
+    "-m",
+    multiple=True,
+    required=True,
+    help="Path to a .metadata.yml file (can be specified multiple times)",
+)
+@click.option("--json-output", "--json", "output_json", is_flag=True, help="Output as JSON")
+@click.option("--repo-dir", default=".", help="Path to the git repository")
+def main(
+    start: str,
+    end: str,
+    metadata: tuple[str, ...],
+    output_json: bool,
+    repo_dir: str,
+) -> None:
+    """Detect which playbooks are triggered by git changes between START and END refs.
+
+    Reads .metadata.yml files that map file glob patterns to playbook names,
+    then checks the git diff to determine which playbooks should run.
+    """
+    try:
+        result = detect_changes(
+            start=start,
+            end=end,
+            metadata_files=list(metadata),
+            repo_dir=repo_dir,
+        )
+    except Exception as e:
+        click.echo(f"Error: {e}", err=True)
+        sys.exit(1)
+
+    if output_json:
+        # Strip matched_files for clean CI output
+        clean = {
+            name: {
+                "triggered": info["triggered"],
+                "stage": info["stage"],
+                "depends_on": info["depends_on"],
+            }
+            for name, info in result.items()
+        }
+        click.echo(json.dumps(clean, indent=2))
+    else:
+        triggered = [n for n, i in result.items() if i["triggered"]]
+        skipped = [n for n, i in result.items() if not i["triggered"]]
+
+        if triggered:
+            click.echo("Triggered playbooks:")
+            for name in sorted(triggered):
+                info = result[name]
+                click.echo(f"  ▶ {name} (stage {info['stage']})")
+                for f in info["matched_files"]:
+                    click.echo(f"    └─ {f}")
+        else:
+            click.echo("No playbooks triggered.")
+
+        if skipped:
+            click.echo(f"\nSkipped: {', '.join(sorted(skipped))}")
+
+
+if __name__ == "__main__":
+    main()

src/git_change_detection/detector.py

@@ -0,0 +1,116 @@
+"""Core detection logic: match git diff against metadata to find triggered playbooks."""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import subprocess
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def get_changed_files(start: str, end: str, repo_dir: str = ".") -> list[str]:
+    """Return list of files changed between two git refs."""
+    result = subprocess.run(
+        ["git", "diff", "--name-only", f"{start}...{end}"],
+        capture_output=True,
+        text=True,
+        cwd=repo_dir,
+        check=True,
+    )
+    return [f.strip() for f in result.stdout.strip().splitlines() if f.strip()]
+
+
+def load_metadata(path: str) -> dict[str, Any]:
+    """Load a .metadata.yml file.
+
+    Expected format:
+        playbook_name:
+          stage: 1
+          depends_on: []
+          paths:
+            - "ansible/roles/my_role/**"
+            - "ansible/inventory/*/group_vars/**"
+    """
+    with open(path) as f:
+        data = yaml.safe_load(f)
+    return data or {}
+
+
+def match_paths(changed_files: list[str], patterns: list[str]) -> bool:
+    """Check if any changed file matches any of the glob patterns."""
+    for changed in changed_files:
+        for pattern in patterns:
+            if fnmatch.fnmatch(changed, pattern):
+                return True
+    return False
+
+
+def detect_changes(
+    start: str,
+    end: str,
+    metadata_files: list[str],
+    repo_dir: str = ".",
+) -> dict[str, Any]:
+    """Run change detection and return playbook trigger map.
+
+    Returns a dict like:
+        {
+            "playbook_name": {
+                "triggered": true,
+                "stage": 1,
+                "depends_on": [],
+                "matched_files": ["path/to/file"]
+            }
+        }
+    """
+    changed_files = get_changed_files(start, end, repo_dir)
+
+    result: dict[str, Any] = {}
+
+    for meta_path in metadata_files:
+        metadata = load_metadata(meta_path)
+
+        for playbook_name, config in metadata.items():
+            if not isinstance(config, dict):
+                continue
+
+            patterns = config.get("paths", [])
+            stage = config.get("stage", 0)
+            depends_on = config.get("depends_on", [])
+
+            matched = [
+                f for f in changed_files
+                if any(fnmatch.fnmatch(f, p) for p in patterns)
+            ]
+
+            triggered = len(matched) > 0
+
+            if playbook_name in result:
+                if triggered:
+                    result[playbook_name]["triggered"] = True
+                    result[playbook_name]["matched_files"].extend(matched)
+            else:
+                result[playbook_name] = {
+                    "triggered": triggered,
+                    "stage": stage,
+                    "depends_on": depends_on,
+                    "matched_files": matched,
+                }
+
+    # Propagate triggers through dependencies
+    changed = True
+    while changed:
+        changed = False
+        for name, info in result.items():
+            if info["triggered"]:
+                continue
+            for dep in info["depends_on"]:
+                if dep in result and result[dep]["triggered"]:
+                    info["triggered"] = True
+                    changed = True
+                    break
+
+    return result