github-overlord 0.9.1__tar.gz → 0.10.0__tar.gz

{github_overlord-0.9.1 → github_overlord-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: github-overlord
-Version: 0.9.1
+Version: 0.10.0
 Summary: Automatically merge Dependabot PRs in public repositories
 Keywords: github,dependabot,automation
 Author: Michael Bianco
@@ -20,6 +20,7 @@ Requires-Dist: apscheduler>=3.10.4
 Requires-Dist: openai>=1.52.2,<4.0.0
 Requires-Dist: pydantic-ai-slim[google]>=0.0.18
 Requires-Dist: jinja2>=3.1.0
+Requires-Dist: pyyaml>=6.0.3
 Requires-Python: >=3.12
 Project-URL: Homepage, https://github.com/iloveitaly/github-overlord
 Project-URL: Repository, https://github.com/iloveitaly/github-overlord
@@ -92,13 +93,15 @@ github-overlord generate-releases --topic auto-release --dry-run
 * `--topic` flag or `RELEASE_CHECKER_TOPIC` - Topic to filter repositories (required unless using `--repo`)
 * `--repo` flag or `RELEASE_CHECKER_REPO` - Single repository to process (useful for testing)
 * `RELEASE_CHECKER_MIN_GAP` - Minimum time between releases for the same repo (defaults to `2w`, e.g. `14d`, `48h`)
+* `RELEASE_CHECKER_GLOBAL_MIN_GAP` - Minimum time between releases created by this tool across the repositories in that run (defaults to `1w`; set to `0` to disable). The clock is the newest GitHub release, among those repos, whose notes include this tool's `Generated-by` line, using that release's publish time. Manual releases do not reset it. While this gap is active, a run creates at most one release even if `--max-releases` is higher.
 
 **How it works:**
 
 1. Finds repositories matching the specified topic
-2. For each repo, gets commits since the last release (or since repo creation if no releases)
-3. Analyzes up to the last 50 commits using the configured AI model (defaulting to `gemini-3.8-flash`) to determine if a release is warranted
-4. If the LLM recommends a release, automatically creates one with:
+2. Finds the newest release published by this tool across those repositories. If that publish time is newer than `RELEASE_CHECKER_GLOBAL_MIN_GAP`, the run stops
+3. For each remaining repo, skips it when its latest release is newer than `RELEASE_CHECKER_MIN_GAP`, then reads commits since that release (or since the repo was created)
+4. Analyzes up to the last 50 commits using the configured AI model (defaulting to `gemini-3.8-flash`) to determine if a release is warranted
+5. If the LLM recommends a release, automatically creates one with:
 
     * Auto-incremented semantic version (patch/minor/major based on changes)
     * AI-generated release notes highlighting key changes

{github_overlord-0.9.1 → github_overlord-0.10.0}/README.md

@@ -65,13 +65,15 @@ github-overlord generate-releases --topic auto-release --dry-run
 * `--topic` flag or `RELEASE_CHECKER_TOPIC` - Topic to filter repositories (required unless using `--repo`)
 * `--repo` flag or `RELEASE_CHECKER_REPO` - Single repository to process (useful for testing)
 * `RELEASE_CHECKER_MIN_GAP` - Minimum time between releases for the same repo (defaults to `2w`, e.g. `14d`, `48h`)
+* `RELEASE_CHECKER_GLOBAL_MIN_GAP` - Minimum time between releases created by this tool across the repositories in that run (defaults to `1w`; set to `0` to disable). The clock is the newest GitHub release, among those repos, whose notes include this tool's `Generated-by` line, using that release's publish time. Manual releases do not reset it. While this gap is active, a run creates at most one release even if `--max-releases` is higher.
 
 **How it works:**
 
 1. Finds repositories matching the specified topic
-2. For each repo, gets commits since the last release (or since repo creation if no releases)
-3. Analyzes up to the last 50 commits using the configured AI model (defaulting to `gemini-3.8-flash`) to determine if a release is warranted
-4. If the LLM recommends a release, automatically creates one with:
+2. Finds the newest release published by this tool across those repositories. If that publish time is newer than `RELEASE_CHECKER_GLOBAL_MIN_GAP`, the run stops
+3. For each remaining repo, skips it when its latest release is newer than `RELEASE_CHECKER_MIN_GAP`, then reads commits since that release (or since the repo was created)
+4. Analyzes up to the last 50 commits using the configured AI model (defaulting to `gemini-3.8-flash`) to determine if a release is warranted
+5. If the LLM recommends a release, automatically creates one with:
 
     * Auto-incremented semantic version (patch/minor/major based on changes)
     * AI-generated release notes highlighting key changes

{github_overlord-0.9.1 → github_overlord-0.10.0}/github_overlord/__init__.py

@@ -1,19 +1,47 @@
 import os
 
 import click
-from github import Github
+from github import Github, GithubException
 
 import github_overlord.patch  # noqa: F401
 
 from .ai import get_expected_ai_key_var, is_ai_key_configured
 from .dependabot import dependabot
 from .notifications import notifications
-from .release_checker import check_repo_for_release
+from .release_checker import (
+    check_repo_for_release,
+    get_global_min_release_gap,
+    release_creation_blocked_by_global_gap,
+    should_stop_for_global_gap,
+)
 from .stale_commenter import inspect_stale_prs
 from .utils import extract_repo_reference_from_github_url, log
 from .version import __version__
 
 
+def _log_release_run_summary(
+    dry_run: bool, *, checked: int, created: int, skipped: int, failed: int
+) -> None:
+    if dry_run:
+        log.info(
+            "release check complete",
+            dry_run=True,
+            checked=checked,
+            would_create=created,
+            skipped=skipped,
+            errors=failed,
+        )
+        return
+
+    log.info(
+        "release check complete",
+        checked=checked,
+        created=created,
+        skipped=skipped,
+        failed=failed,
+    )
+
+
 def _ensure_ai_key_configured(command_action: str) -> None:
     if not is_ai_key_configured():
         expected_var = get_expected_ai_key_var()
@@ -120,9 +148,48 @@ def generate_releases(dry_run, topic, repo, max_releases):
 
     repo = extract_repo_reference_from_github_url(repo)
 
+    # Topic is required when not specifying a single repo
+    if not repo and not topic:
+        raise click.UsageError(
+            "Topic is required when not specifying a single repository (use --topic or set RELEASE_CHECKER_TOPIC)"
+        )
+
+    g = Github(token)
     if repo:
-        g = Github(token)
-        result = check_repo_for_release(g.get_repo(repo), dry_run)
+        candidates = [g.get_repo(repo)]
+    else:
+        user = g.get_user()
+        log.info("filtering by topic", topic=topic)
+        # Public repos owned by the user with the specified topic.
+        candidates = list(
+            g.search_repositories(
+                f"user:{user.login} topic:{topic} fork:false is:public",
+                sort="updated",
+                order="desc",
+            )
+        )
+        if not candidates:
+            log.warning("no repositories found with topic", topic=topic)
+            return
+
+    global_gap = get_global_min_release_gap()
+    try:
+        blocked = release_creation_blocked_by_global_gap(candidates, gap=global_gap)
+    except GithubException:
+        log.error(
+            "skipping release creation because global gap state could not be read"
+        )
+        return
+
+    if blocked:
+        if repo:
+            log.info("release check complete - no release needed", dry_run=dry_run)
+        else:
+            _log_release_run_summary(dry_run, checked=0, created=0, skipped=0, failed=0)
+        return
+
+    if repo:
+        result = check_repo_for_release(candidates[0], dry_run)
         if result["created"]:
             log.info("release check complete - created 1 release", dry_run=dry_run)
         elif result["failed"]:
@@ -133,32 +200,10 @@ def generate_releases(dry_run, topic, repo, max_releases):
             log.info("release check complete - no release needed", dry_run=dry_run)
         return
 
-    # Topic is required when not specifying a single repo
-    if not topic:
-        raise click.UsageError(
-            "Topic is required when not specifying a single repository (use --topic or set RELEASE_CHECKER_TOPIC)"
-        )
-
-    g = Github(token)
-    user = g.get_user()
-
-    log.info("filtering by topic", topic=topic)
-
-    # Get all public repos owned by user with the specified topic
-    repos = g.search_repositories(
-        f"user:{user.login} topic:{topic} fork:false is:public",
-        sort="updated",
-        order="desc",
-    )
-
-    def _check_repo_with_log(r):
-        log.info("checking repo for release", repo=r.full_name, dry_run=dry_run)
-        return check_repo_for_release(r, dry_run=dry_run)
-
     results = []
     created_count = 0
 
-    for r in repos:
+    for candidate in candidates:
         if max_releases > 0 and created_count >= max_releases:
             log.info(
                 "reached max releases limit for this run",
@@ -166,40 +211,29 @@ def generate_releases(dry_run, topic, repo, max_releases):
             )
             break
 
-        res = _check_repo_with_log(r)
-        results.append(res)
-        if res["created"]:
+        log.info("checking repo for release", repo=candidate.full_name, dry_run=dry_run)
+        result = check_repo_for_release(candidate, dry_run=dry_run)
+        results.append(result)
+        if result["created"]:
             created_count += 1
-
-    # Check if any repos were found
-    if not results:
-        log.warning("no repositories found with topic", topic=topic)
-        return
-
-    # Calculate statistics
-    total_checked = sum(1 for r in results if r["checked"])
-    total_skipped = sum(1 for r in results if r["skipped"])
-    total_created = sum(1 for r in results if r["created"])
-    total_failed = sum(1 for r in results if r["failed"])
-
-    # Log summary
-    if dry_run:
-        log.info(
-            "release check complete",
-            dry_run=True,
-            checked=total_checked,
-            would_create=total_created,
-            skipped=total_skipped,
-            errors=total_failed,
-        )
-    else:
-        log.info(
-            "release check complete",
-            checked=total_checked,
-            created=total_created,
-            skipped=total_skipped,
-            failed=total_failed,
-        )
+            if should_stop_for_global_gap(global_gap, max_releases, created_count):
+                log.info(
+                    "stopping after one auto-generated release to honor global minimum gap",
+                    min_gap_seconds=int(global_gap.total_seconds()),
+                )
+                break
+
+    total_checked = sum(1 for result in results if result["checked"])
+    total_skipped = sum(1 for result in results if result["skipped"])
+    total_created = sum(1 for result in results if result["created"])
+    total_failed = sum(1 for result in results if result["failed"])
+    _log_release_run_summary(
+        dry_run,
+        checked=total_checked,
+        created=total_created,
+        skipped=total_skipped,
+        failed=total_failed,
+    )
 
 
 cli.add_command(dependabot)

{github_overlord-0.9.1 → github_overlord-0.10.0}/github_overlord/release_checker.py

@@ -7,6 +7,8 @@ calculates semantic version bumps, and generates formatted release notes.
 
 import os
 import re
+from collections.abc import Iterable
+from dataclasses import dataclass
 from datetime import UTC, datetime, timedelta
 
 from github import GithubException
@@ -21,6 +23,9 @@ from github_overlord.ai import (
 from github_overlord.config import JINJA_ENV
 from github_overlord.utils import log
 
+# Release notes include this line. It is how a later run recognizes its own releases.
+GENERATED_BY_MARKER = "**Generated-by**: https://github.com/iloveitaly/github-overlord"
+
 
 def _parse_duration_to_timedelta(value: str) -> timedelta:
     """Parse a simple duration string into a timedelta.
@@ -56,29 +61,168 @@ def _parse_duration_to_timedelta(value: str) -> timedelta:
     raise ValueError(f"unsupported duration unit: {unit!r}")
 
 
-def _get_min_release_gap() -> timedelta:
-    raw = os.getenv("RELEASE_CHECKER_MIN_GAP", "2w")
+def _get_configured_gap(
+    env_var: str,
+    default: str,
+    *,
+    invalid_event: str,
+    negative_event: str,
+) -> timedelta:
+    raw = os.getenv(env_var, default)
     try:
         gap = _parse_duration_to_timedelta(raw)
     except ValueError:
-        log.warning(
-            "invalid release_checker_min_gap; falling back to default",
-            value=raw,
-            default="2w",
-        )
-        gap = timedelta(weeks=2)
+        log.warning(invalid_event, value=raw, default=default)
+        gap = _parse_duration_to_timedelta(default)
 
     if gap.total_seconds() < 0:
-        log.warning(
-            "negative release_checker_min_gap; falling back to default",
-            value=raw,
-            default="2w",
-        )
-        return timedelta(weeks=2)
+        log.warning(negative_event, value=raw, default=default)
+        return _parse_duration_to_timedelta(default)
 
     return gap
 
 
+def _get_min_release_gap() -> timedelta:
+    return _get_configured_gap(
+        "RELEASE_CHECKER_MIN_GAP",
+        "2w",
+        invalid_event="invalid release_checker_min_gap; falling back to default",
+        negative_event="negative release_checker_min_gap; falling back to default",
+    )
+
+
+def get_global_min_release_gap() -> timedelta:
+    """Minimum time between auto-generated releases across the selected repos.
+
+    Defaults to one week. ``0`` disables the limit.
+    """
+
+    return _get_configured_gap(
+        "RELEASE_CHECKER_GLOBAL_MIN_GAP",
+        "1w",
+        invalid_event="invalid release_checker_global_min_gap; falling back to default",
+        negative_event="negative release_checker_global_min_gap; falling back to default",
+    )
+
+
+def _as_utc(value: datetime) -> datetime:
+    if value.tzinfo is None:
+        return value.replace(tzinfo=UTC)
+    return value.astimezone(UTC)
+
+
+def _is_generated_release(release: object) -> bool:
+    body = getattr(release, "body", None) or ""
+    if not isinstance(body, str):
+        return False
+    return GENERATED_BY_MARKER in body
+
+
+def _published_at(release: object) -> datetime | None:
+    published = getattr(release, "published_at", None)
+    if not isinstance(published, datetime):
+        return None
+    return _as_utc(published)
+
+
+@dataclass(frozen=True)
+class GeneratedRelease:
+    """An auto-generated GitHub release, identified by its release notes."""
+
+    repo_full_name: str
+    tag_name: str
+    published_at: datetime
+
+
+def latest_generated_release_since(
+    repos: Iterable[Repository], since: datetime
+) -> GeneratedRelease | None:
+    """Return the newest auto-generated release published after ``since``.
+
+    GitHub lists releases by ``created_at``, and that field is the tagged
+    commit's timestamp, not when the release was published. A release published
+    today for an older commit can sort behind a newer commit, so this compares
+    ``published_at`` across the full list. Manual releases are ignored.
+    """
+
+    since = _as_utc(since)
+    latest: GeneratedRelease | None = None
+
+    for repo in repos:
+        try:
+            for release in repo.get_releases():
+                published_at = _published_at(release)
+                if published_at is None or published_at <= since:
+                    continue
+                if latest is not None and published_at <= latest.published_at:
+                    continue
+                if not _is_generated_release(release):
+                    continue
+                latest = GeneratedRelease(
+                    repo_full_name=repo.full_name,
+                    tag_name=release.tag_name,
+                    published_at=published_at,
+                )
+        except GithubException as error:
+            log.error(
+                "failed to list releases while checking global gap",
+                repo=getattr(repo, "full_name", None),
+                error=str(error),
+            )
+            raise
+
+    return latest
+
+
+def release_creation_blocked_by_global_gap(
+    repos: Iterable[Repository],
+    *,
+    now: datetime | None = None,
+    gap: timedelta | None = None,
+) -> bool:
+    """Return whether an auto-generated release is still inside the global gap.
+
+    A gap of zero disables the check. The clock is the newest published
+    auto-generated release among ``repos``.
+    """
+
+    gap = get_global_min_release_gap() if gap is None else gap
+    if gap.total_seconds() <= 0:
+        return False
+
+    now = _as_utc(now or datetime.now(UTC))
+    latest = latest_generated_release_since(repos, now - gap)
+    if latest is None:
+        return False
+
+    time_since = now - latest.published_at
+    log.info(
+        "skipping release check due to global minimum gap",
+        last_release=latest.tag_name,
+        last_release_repo=latest.repo_full_name,
+        time_since_release_seconds=int(time_since.total_seconds()),
+        min_gap_seconds=int(gap.total_seconds()),
+    )
+    return True
+
+
+def should_stop_for_global_gap(
+    gap: timedelta, max_releases: int, created_count: int
+) -> bool:
+    """Return whether this run should stop after creating an auto-generated release.
+
+    A positive global gap allows one new auto-generated release per interval.
+    ``max_releases`` still caps a run on its own when the global gap is disabled.
+    """
+
+    if gap.total_seconds() <= 0 or created_count < 1:
+        return False
+    # max_releases <= 0 means unlimited for the run; the global gap is the cap.
+    if max_releases <= 0:
+        return True
+    return created_count < max_releases
+
+
 class ReleaseAnalysis(BaseModel):
     """Structured output from LLM analysis of commits."""
 
@@ -339,9 +483,7 @@ def generate_release_notes(
         changelog_url = f"https://github.com/{repo.full_name}/commits/{new_tag}"
 
     notes_parts.append(f"**Full Changelog**: {changelog_url}")
-    notes_parts.append(
-        "**Generated-by**: https://github.com/iloveitaly/github-overlord"
-    )
+    notes_parts.append(GENERATED_BY_MARKER)
 
     return "\n".join(notes_parts)
 
@@ -381,6 +523,9 @@ def check_repo_for_release(repo: Repository, dry_run: bool) -> dict:
     """
     Check a single repository and create a release if recommended.
 
+    The cross-repo ``RELEASE_CHECKER_GLOBAL_MIN_GAP`` is enforced by the
+    generate-releases command before this function is called.
+
     Returns:
         dict with keys: checked, skipped, created, failed
     """

{github_overlord-0.9.1 → github_overlord-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "github-overlord"
-version = "0.9.1"
+version = "0.10.0"
 description = "Automatically merge Dependabot PRs in public repositories"
 readme = "README.md"
 keywords = [
@@ -26,6 +26,7 @@ dependencies = [
     "openai>=1.52.2,<4.0.0",
     "pydantic-ai-slim[google]>=0.0.18",
     "jinja2>=3.1.0",
+    "pyyaml>=6.0.3",
 ]
 
 [[project.authors]]

{github_overlord-0.9.1 → github_overlord-0.10.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "github-overlord"
-version = "0.9.1"
+version = "0.10.0"
 description = "Automatically merge Dependabot PRs in public repositories"
 authors = [{ name = "Michael Bianco", email = "mike@mikebian.co" }]
 readme = "README.md"
@@ -24,6 +24,7 @@ dependencies = [
     "openai>=1.52.2,<4.0.0",
     "pydantic-ai-slim[google]>=0.0.18",
     "jinja2>=3.1.0",
+    "pyyaml>=6.0.3",
 ]
 
 [project.urls]