GRM-37: feat: Smart CI and release skipping for workflow-only changes

scripts/classify_changes.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""Classify git changes as user-facing or workflow-only.
+
+Determines whether changes between two git refs (e.g., last tag and HEAD)
+affect the GRM tool itself (user-facing) or only the CI/CD infrastructure
+(workflow-only).  This is used by:
+
+- **release.py** — skips release when only workflow files changed
+- **CI workflow** — skips molecule tests and release dry-run when only
+  workflow files changed
+
+Classification rules:
+
+  User-facing paths (tool changes → release needed):
+    - src/gitea_runner_manager/**  — Python CLI source
+    - ansible/**                   — Ansible role
+    - pyproject.toml               — Package metadata
+
+  Workflow-only paths (infrastructure → no release needed):
+    - .gitea/workflows/**          — Gitea Actions workflows
+    - scripts/**                   — CI/CD automation scripts
+    - docs/**                      — Documentation
+    - tests/**                     — Test files
+    - hooks/**                     — Git hooks
+    - AGENTS.md                    — Agent conventions
+    - README.md                    — README (lean, links to wiki)
+    - CHANGELOG.md                 — Changelog (generated)
+    - TROUBLESHOOTING.md           — Troubleshooting guide
+    - cliff.toml                   — git-cliff config
+    - Makefile                     — Build automation
+    - .pre-commit-config.yaml      — Pre-commit config
+    - .ansible-lint                — Ansible lint config
+    - .env.example                 — Environment template
+    - .gitignore                   — Git ignore rules
+
+Usage:
+  python3 scripts/classify_changes.py [--base <ref>] [--head <ref>]
+  python3 scripts/classify_changes.py --base v0.3.0 --head HEAD
+"""
+
+from __future__ import annotations
+
+import subprocess  # nosec B404
+import sys
+
+import click
+
+from gitea_runner_manager.i18n import _
+
+# Paths that count as user-facing (tool changes)
+USER_FACING_PATTERNS = frozenset(
+    [
+        "src/gitea_runner_manager/",
+        "ansible/",
+        "pyproject.toml",
+    ]
+)
+
+
+def run_git(args: list[str]) -> str:
+    """Run a git command and return stdout."""
+    result = subprocess.run(  # nosec B603
+        args,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise click.ClickException(
+            _("git command failed ({cmd}): {stderr}", cmd=" ".join(args), stderr=result.stderr.strip())
+        )
+    return result.stdout.strip()
+
+
+def get_changed_files(base: str, head: str) -> list[str]:
+    """Get list of files changed between base and head refs."""
+    output = run_git(["git", "diff", "--name-only", base, head])
+    if not output:
+        return []
+    return output.split("\n")
+
+
+def is_user_facing(file_path: str) -> bool:
+    """Check if a file path is user-facing (affects the GRM tool)."""
+    return any(file_path.startswith(pattern) or file_path == pattern for pattern in USER_FACING_PATTERNS)
+
+
+def classify_changes(files: list[str]) -> dict[str, list[str]]:
+    """Classify changed files into user-facing and workflow-only.
+
+    Returns a dict with keys "user_facing" and "workflow_only".
+    """
+    user_facing: list[str] = []
+    workflow_only: list[str] = []
+    for f in files:
+        if is_user_facing(f):
+            user_facing.append(f)
+        else:
+            workflow_only.append(f)
+    return {"user_facing": user_facing, "workflow_only": workflow_only}
+
+
+def has_user_facing_changes(base: str, head: str) -> bool:
+    """Check if any user-facing files changed between base and head."""
+    files = get_changed_files(base, head)
+    return any(is_user_facing(f) for f in files)
+
+
+def get_latest_tag() -> str:
+    """Get the latest git tag, or empty string if none exists."""
+    result = subprocess.run(  # nosec B603 B607
+        ["git", "describe", "--tags", "--abbrev=0"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        return ""
+    return result.stdout.strip()
+
+
+@click.command()
+@click.option("--base", default=None, help="Base ref (default: latest tag).")
+@click.option("--head", default="HEAD", help="Head ref (default: HEAD).")
+@click.option("--quiet", is_flag=True, default=False, help="Only output true/false.")
+def main(base: str | None, head: str, quiet: bool) -> None:
+    if base is None:
+        base = get_latest_tag()
+        if not base:
+            if quiet:
+                click.echo("true")
+            else:
+                click.echo(_("No tags found — treating all changes as user-facing."))
+            return
+
+    files = get_changed_files(base, head)
+    if not files:
+        if quiet:
+            click.echo("false")
+        else:
+            click.echo(_("No changes between {base} and {head}.", base=base, head=head))
+        return
+
+    result = classify_changes(files)
+    has_user = bool(result["user_facing"])
+
+    if quiet:
+        click.echo("true" if has_user else "false")
+        return
+
+    click.echo(_("Comparing {base}..{head} ({count} files changed)", base=base, head=head, count=len(files)))
+    click.echo(_("\nUser-facing changes ({count}):", count=len(result["user_facing"])))
+    for f in result["user_facing"]:
+        click.echo(f"  {f}")
+    click.echo(_("\nWorkflow-only changes ({count}):", count=len(result["workflow_only"])))
+    for f in result["workflow_only"]:
+        click.echo(f"  {f}")
+    if has_user:
+        status = "USER-FACING changes detected — release needed"
+    else:
+        status = "Workflow-only changes — no release needed"
+    click.echo(_("\nResult: {status}", status=status))
+
+    if not has_user:
+        sys.exit(2)  # Exit code 2 = workflow-only (used by CI to skip release)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

scripts/doc_coverage.py

@@ -42,6 +42,7 @@ REQUIRED_SCRIPTS = [
     "review_pr.py",
     "notify_failure.py",
     "post_merge.py",
+    "classify_changes.py",
 ]
 
 

scripts/release.py

@@ -36,6 +36,7 @@ import click
 from dotenv import load_dotenv  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
 
 from gitea_runner_manager.i18n import _
+from scripts.classify_changes import has_user_facing_changes
 
 load_dotenv(override=True)
 
@@ -256,6 +257,18 @@ def main(dry_run: bool, skip_tests: bool) -> None:
     if branch != "master":
         raise click.ClickException(_("Release must be run on master, currently on '{branch}'.", branch=branch))
 
+    # Check if any user-facing files changed since the last tag.
+    # If only workflow/infra files changed, skip the release entirely.
+    latest_tag = get_latest_tag()
+    if latest_tag and not has_user_facing_changes(latest_tag, "HEAD"):
+        click.echo(
+            _(
+                "No user-facing changes since {tag} — only workflow/infrastructure files changed. Skipping release.",
+                tag=latest_tag,
+            )
+        )
+        return
+
     # Calculate next version (single git-cliff call — Gap 7 fix)
     new_version = get_bumped_version()