migrate: Add ruleset helpers to the template

Copy the reusable GitHub ruleset helper functions to the migration
script template so future migration steps can query and update rulesets
without duplicating API plumbing.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Author: llucax

.github/cookiecutter-migrate.template.py

@@ -28,7 +28,7 @@
 import sys
 import tempfile
 from pathlib import Path
-from typing import SupportsIndex
+from typing import Any, SupportsIndex
 
 _manual_steps: list[str] = []  # pylint: disable=invalid-name
 
@@ -180,6 +180,132 @@ def calculate_file_sha256_skip_lines(filepath: Path, skip_lines: int) -> str | N
     return hashlib.sha256(remaining_content.encode()).hexdigest()
 
 
+def find_ruleset(name: str) -> dict[str, Any] | None:
+    """Find a repository ruleset by name using the GitHub API.
+
+    Args:
+        name: The name of the ruleset to search for.
+
+    Returns:
+        The ruleset summary dict (id, name, …) if found, or ``None`` if not
+        found or if the API call failed (a diagnostic is printed in the latter
+        case).
+    """
+    try:
+        stdout = subprocess.check_output(
+            ["gh", "api", "repos/:owner/:repo/rulesets"],
+            text=True,
+            stderr=subprocess.PIPE,
+        )
+    except FileNotFoundError:
+        print("  gh CLI not found; cannot query rulesets via the GitHub API.")
+        return None
+    except subprocess.CalledProcessError as exc:
+        print(f"  Failed to list rulesets: {exc.stderr.strip()}")
+        return None
+
+    rulesets: list[dict[str, Any]] = json.loads(stdout)
+    return next((r for r in rulesets if r.get("name") == name), None)
+
+
+def get_ruleset(ruleset: str | int) -> dict[str, Any] | None:
+    """Fetch the full details of a repository ruleset by name or ID.
+
+    Args:
+        ruleset: The ruleset name (``str``) or numeric ruleset ID (``int``).
+
+    Returns:
+        The full ruleset dict, or ``None`` if the ruleset could not be found
+        or the API call failed (a diagnostic is printed).
+    """
+    ruleset_id = ruleset
+    if isinstance(ruleset, str):
+        entry = find_ruleset(ruleset)
+        if entry is None:
+            return None
+        ruleset_id = entry["id"]
+
+    try:
+        stdout = subprocess.check_output(
+            ["gh", "api", f"repos/:owner/:repo/rulesets/{ruleset_id}"],
+            text=True,
+            stderr=subprocess.PIPE,
+        )
+    except subprocess.CalledProcessError as exc:
+        print(f"  Failed to fetch ruleset {ruleset_id}: {exc.stderr.strip()}")
+        return None
+
+    return json.loads(stdout)  # type: ignore[no-any-return]
+
+
+def update_ruleset(ruleset_id: int, config: dict[str, Any]) -> bool:
+    """Update a repository ruleset via the GitHub API.
+
+    Only ``name``, ``target``, ``enforcement``, ``conditions``, ``rules``,
+    and ``bypass_actors`` are sent (explicit allowlist to avoid sending
+    read-only fields back to the API).
+
+    Args:
+        ruleset_id: The numeric ruleset ID to update.
+        config: The full ruleset dict (as returned by :func:`get_ruleset`)
+            with the desired changes already applied in-memory.
+
+    Returns:
+        ``True`` on success, ``False`` if the API call failed (a diagnostic
+        is printed).
+    """
+    payload: dict[str, Any] = {
+        "name": config["name"],
+        "target": config["target"],
+        "enforcement": config["enforcement"],
+        "conditions": config["conditions"],
+        "rules": config["rules"],
+    }
+    if "bypass_actors" in config:
+        payload["bypass_actors"] = config["bypass_actors"]
+
+    try:
+        subprocess.check_output(
+            [
+                "gh",
+                "api",
+                "-X",
+                "PUT",
+                f"repos/:owner/:repo/rulesets/{ruleset_id}",
+                "--input",
+                "-",
+            ],
+            input=json.dumps(payload),
+            text=True,
+            stderr=subprocess.PIPE,
+        )
+    except subprocess.CalledProcessError as exc:
+        print(f"  Failed to update ruleset {ruleset_id}: {exc.stderr.strip()}")
+        return False
+
+    return True
+
+
+def get_ruleset_settings_url() -> str | None:
+    """Return the URL to the repository's ruleset settings page.
+
+    Returns:
+        The URL as a string, or ``None`` if it could not be determined.
+    """
+    try:
+        stdout = subprocess.check_output(
+            ["gh", "repo", "view", "--json", "owner,name"],
+            text=True,
+            stderr=subprocess.PIPE,
+        )
+        info: dict[str, Any] = json.loads(stdout)
+        org = info["owner"]["login"]
+        repo = info["name"]
+        return f"https://github.com/{org}/{repo}/settings/rules"
+    except (subprocess.CalledProcessError, KeyError, json.JSONDecodeError):
+        return None
+
+
 def manual_step(message: str) -> None:
     """Print a manual step message in yellow."""
     _manual_steps.append(message)