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

github_overlord-0.9.1/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.3
+Name: github-overlord
+Version: 0.9.1
+Summary: Automatically merge Dependabot PRs in public repositories
+Keywords: github,dependabot,automation
+Author: Michael Bianco
+Author-email: Michael Bianco <mike@mikebian.co>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: pygithub>=2.4.0
+Requires-Dist: click>=8.1.7
+Requires-Dist: python-decouple-typed>=3.11.0
+Requires-Dist: funcy-pipe>=0.11.1,<0.15.0
+Requires-Dist: structlog>=24.4,<27.0
+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-Python: >=3.12
+Project-URL: Homepage, https://github.com/iloveitaly/github-overlord
+Project-URL: Repository, https://github.com/iloveitaly/github-overlord
+Description-Content-Type: text/markdown
+
+[![Release Notes](https://img.shields.io/github/release/iloveitaly/github-overlord)](https://github.com/iloveitaly/github-overlord/releases)
+[![Downloads](https://static.pepy.tech/badge/github-overlord/month)](https://pepy.tech/project/github-overlord)
+[![Python Versions](https://img.shields.io/pypi/pyversions/github-overlord)](https://pypi.org/project/github-overlord)
+![GitHub CI Status](https://github.com/iloveitaly/github-overlord/actions/workflows/build_and_publish.yml/badge.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+# GitHub Overlord
+
+GitHub Overlord is a Python script that does a couple things to help manage open source projects on GitHub:
+
+* Automatically merges Dependabot PRs in public repositories that have passed CI checks.
+* Comment on PRs that are going to automatically be marked as stale
+* Removes notifications from bot-authored PRs, Release Please PRs, self-authored PR creations without external activity, PRs merged by you, PRs closed by you, PRs approved by you that are now merged, notifications older than two months, and releases on repos you control
+* Automatically creates releases for repositories based on LLM analysis of recent commits
+
+This simple project has also given me the chance to iterate on my [nixpacks github actions project](https://github.com/iloveitaly/github-action-nixpacks).
+
+## Installation
+
+```shell
+pip install github-overlord
+```
+
+## Usage
+
+```shell
+Usage: github-overlord [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  generate-releases  Check repositories for release readiness using LLM analysis
+  dependabot      Automatically merge dependabot PRs in public repos that...
+  keep-alive-prs  Detect when a bot is about to close a PR for no good reason
+  notifications   Look at notifications and mark them as read
+```
+
+### Automatic Release Creation
+
+The `generate-releases` command uses LLM analysis (via [Pydantic AI](https://ai.pydantic.dev/)) to determine when repositories are ready for a new release. Both `generate-releases` and `keep-alive-prs` share the same unified AI model configuration (defaulting to Google Gemini `gemini-3.8-flash`).
+
+This is particularly useful for template repositories, starter projects, etc that don't have automated release workflows and aren't versioned for whatever reason.
+
+I have a bunch of these and I wanted an easy way to let the world know when I build something interesting in them.
+
+**Usage:**
+
+```shell
+# Check all repos with a specific topic
+github-overlord generate-releases --topic auto-release
+
+# Check a single repository
+github-overlord generate-releases --repo owner/repo-name
+
+# Dry run (see what would happen without creating releases)
+github-overlord generate-releases --topic auto-release --dry-run
+```
+
+**Requirements & Configuration:**
+
+* `GITHUB_TOKEN` - GitHub token with repo write permissions
+* `GITHUB_OVERLORD_AI_KEY` - API key for the AI provider (or provider-specific `GOOGLE_API_KEY`, `OPENAI_API_KEY`, etc.)
+* `GITHUB_OVERLORD_MODEL` - (Optional) AI model override (e.g. `gemini-3.8-flash`, `openai:gpt-4o`). Defaults to `gemini-3.8-flash`.
+* `--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`)
+
+**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:
+
+    * Auto-incremented semantic version (patch/minor/major based on changes)
+    * AI-generated release notes highlighting key changes
+    * Link to full changelog
+
+**Scheduling:**
+To run this weekly, set the `SCHEDULE` environment variable:
+
+```bash
+# Run every Monday at 9 AM
+export SCHEDULE="0 9 * * 1"
+export RELEASE_CHECKER_TOPIC="template"
+# Or, to test a single repo on the schedule:
+# export RELEASE_CHECKER_REPO="owner/repo-name"
+export GITHUB_TOKEN="your-token"
+export GITHUB_OVERLORD_AI_KEY="your-api-key"
+
+# All CLI commands will run on this schedule
+python main.py
+```
+
+**Troubleshooting:**
+
+* **"No repositories found with topic"**: Make sure your repos have the correct topic tag in GitHub settings
+* **"API key environment variable is required"**: Set `GITHUB_OVERLORD_AI_KEY` (or `GOOGLE_API_KEY` for the default Gemini model). Get a free Gemini API key from [ai.google.dev](https://ai.google.dev/)
+* **Rate limiting**: The free tier has limits (15-60 requests/minute). Consider adding delays between repos if needed
+* **"Failed to create release"**: Ensure `GITHUB_TOKEN` has `repo` scope permissions
+
+### Docker Cron
+
+There's a docker container you can use to run this on a cron. [Fits nicely into a orange pi.](https://mikebian.co/pi-hole-tailscale-and-docker-on-an-orange-pi/)
+
+Check out [docker-compose.yml](./docker-compose.yml) for an example, or `git pull ghcr.io/iloveitaly/github-overlord:latest`.
+
+---
+
+*This project was created from [iloveitaly/python-package-template](https://github.com/iloveitaly/python-package-template)*

github_overlord-0.9.1/README.md

@@ -0,0 +1,111 @@
+[![Release Notes](https://img.shields.io/github/release/iloveitaly/github-overlord)](https://github.com/iloveitaly/github-overlord/releases)
+[![Downloads](https://static.pepy.tech/badge/github-overlord/month)](https://pepy.tech/project/github-overlord)
+[![Python Versions](https://img.shields.io/pypi/pyversions/github-overlord)](https://pypi.org/project/github-overlord)
+![GitHub CI Status](https://github.com/iloveitaly/github-overlord/actions/workflows/build_and_publish.yml/badge.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+# GitHub Overlord
+
+GitHub Overlord is a Python script that does a couple things to help manage open source projects on GitHub:
+
+* Automatically merges Dependabot PRs in public repositories that have passed CI checks.
+* Comment on PRs that are going to automatically be marked as stale
+* Removes notifications from bot-authored PRs, Release Please PRs, self-authored PR creations without external activity, PRs merged by you, PRs closed by you, PRs approved by you that are now merged, notifications older than two months, and releases on repos you control
+* Automatically creates releases for repositories based on LLM analysis of recent commits
+
+This simple project has also given me the chance to iterate on my [nixpacks github actions project](https://github.com/iloveitaly/github-action-nixpacks).
+
+## Installation
+
+```shell
+pip install github-overlord
+```
+
+## Usage
+
+```shell
+Usage: github-overlord [OPTIONS] COMMAND [ARGS]...
+
+Options:
+  --help  Show this message and exit.
+
+Commands:
+  generate-releases  Check repositories for release readiness using LLM analysis
+  dependabot      Automatically merge dependabot PRs in public repos that...
+  keep-alive-prs  Detect when a bot is about to close a PR for no good reason
+  notifications   Look at notifications and mark them as read
+```
+
+### Automatic Release Creation
+
+The `generate-releases` command uses LLM analysis (via [Pydantic AI](https://ai.pydantic.dev/)) to determine when repositories are ready for a new release. Both `generate-releases` and `keep-alive-prs` share the same unified AI model configuration (defaulting to Google Gemini `gemini-3.8-flash`).
+
+This is particularly useful for template repositories, starter projects, etc that don't have automated release workflows and aren't versioned for whatever reason.
+
+I have a bunch of these and I wanted an easy way to let the world know when I build something interesting in them.
+
+**Usage:**
+
+```shell
+# Check all repos with a specific topic
+github-overlord generate-releases --topic auto-release
+
+# Check a single repository
+github-overlord generate-releases --repo owner/repo-name
+
+# Dry run (see what would happen without creating releases)
+github-overlord generate-releases --topic auto-release --dry-run
+```
+
+**Requirements & Configuration:**
+
+* `GITHUB_TOKEN` - GitHub token with repo write permissions
+* `GITHUB_OVERLORD_AI_KEY` - API key for the AI provider (or provider-specific `GOOGLE_API_KEY`, `OPENAI_API_KEY`, etc.)
+* `GITHUB_OVERLORD_MODEL` - (Optional) AI model override (e.g. `gemini-3.8-flash`, `openai:gpt-4o`). Defaults to `gemini-3.8-flash`.
+* `--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`)
+
+**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:
+
+    * Auto-incremented semantic version (patch/minor/major based on changes)
+    * AI-generated release notes highlighting key changes
+    * Link to full changelog
+
+**Scheduling:**
+To run this weekly, set the `SCHEDULE` environment variable:
+
+```bash
+# Run every Monday at 9 AM
+export SCHEDULE="0 9 * * 1"
+export RELEASE_CHECKER_TOPIC="template"
+# Or, to test a single repo on the schedule:
+# export RELEASE_CHECKER_REPO="owner/repo-name"
+export GITHUB_TOKEN="your-token"
+export GITHUB_OVERLORD_AI_KEY="your-api-key"
+
+# All CLI commands will run on this schedule
+python main.py
+```
+
+**Troubleshooting:**
+
+* **"No repositories found with topic"**: Make sure your repos have the correct topic tag in GitHub settings
+* **"API key environment variable is required"**: Set `GITHUB_OVERLORD_AI_KEY` (or `GOOGLE_API_KEY` for the default Gemini model). Get a free Gemini API key from [ai.google.dev](https://ai.google.dev/)
+* **Rate limiting**: The free tier has limits (15-60 requests/minute). Consider adding delays between repos if needed
+* **"Failed to create release"**: Ensure `GITHUB_TOKEN` has `repo` scope permissions
+
+### Docker Cron
+
+There's a docker container you can use to run this on a cron. [Fits nicely into a orange pi.](https://mikebian.co/pi-hole-tailscale-and-docker-on-an-orange-pi/)
+
+Check out [docker-compose.yml](./docker-compose.yml) for an example, or `git pull ghcr.io/iloveitaly/github-overlord:latest`.
+
+---
+
+*This project was created from [iloveitaly/python-package-template](https://github.com/iloveitaly/python-package-template)*

github_overlord-0.9.1/github_overlord/__init__.py

@@ -0,0 +1,211 @@
+import os
+
+import click
+from github import Github
+
+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 .stale_commenter import inspect_stale_prs
+from .utils import extract_repo_reference_from_github_url, log
+from .version import __version__
+
+
+def _ensure_ai_key_configured(command_action: str) -> None:
+    if not is_ai_key_configured():
+        expected_var = get_expected_ai_key_var()
+        raise click.ClickException(
+            click.style(
+                f"{expected_var} (or GITHUB_OVERLORD_AI_KEY) environment variable is required to {command_action}",
+                fg="red",
+            )
+        )
+
+
+@click.group()
+@click.version_option(version=__version__)
+def cli():
+    """
+    GitHub Overlord is a tool to help manage annoying tasks across your GitHub repositories. Some of this could be done
+    by GitHub Actions, but this eliminates the need to carefully configure GH actions for each repo.
+    """
+
+
+@click.command()
+@click.option(
+    "--token",
+    help="GitHub token, can also be set via GITHUB_TOKEN",
+    default=os.getenv("GITHUB_TOKEN"),
+)
+@click.option("--dry-run", is_flag=True, help="Run script without creating comments")
+@click.option("--repo", help="Only process a single repository")
+def keep_alive_prs(token, dry_run, repo):
+    """
+    Detect when a bot is about to close a PR for no good reason and make a comment to keep it alive
+    """
+
+    if not token:
+        raise click.ClickException(
+            click.style("GITHUB_TOKEN environment variable is required", fg="red")
+        )
+
+    _ensure_ai_key_configured("run keep-alive-prs")
+
+    log.info("checking for stale PRs")
+
+    github = Github(token)
+    user = github.get_user()
+    login = user.login
+
+    repo = extract_repo_reference_from_github_url(repo)
+
+    result = inspect_stale_prs(github, login, dry_run, repo)
+    if dry_run:
+        log.info(
+            "stale PR check complete",
+            dry_run=True,
+            prs_inspected=result.inspected,
+            would_keep_alive=result.kept_alive,
+            skipped=result.skipped,
+            failed=result.failed,
+        )
+        return
+
+    log.info(
+        "stale PR check complete",
+        prs_inspected=result.inspected,
+        kept_alive=result.kept_alive,
+        skipped=result.skipped,
+        failed=result.failed,
+    )
+
+
+@click.command(name="generate-releases")
+@click.option("--dry-run", is_flag=True, help="Run script without creating releases")
+@click.option(
+    "--topic",
+    help="Only process repos with this topic (can also be set via RELEASE_CHECKER_TOPIC)",
+    default=os.getenv("RELEASE_CHECKER_TOPIC"),
+)
+@click.option(
+    "--repo",
+    help="Only process a single repository (can also be set via RELEASE_CHECKER_REPO)",
+    default=os.getenv("RELEASE_CHECKER_REPO"),
+)
+@click.option(
+    "--max-releases",
+    "-m",
+    type=int,
+    default=lambda: int(os.getenv("RELEASE_CHECKER_MAX_RELEASES", "1")),
+    show_default="1",
+    help="Maximum number of releases to create in a single run (0 for unlimited)",
+)
+def generate_releases(dry_run, topic, repo, max_releases):
+    """
+    Check repositories for release readiness using LLM analysis and create releases when appropriate
+    """
+
+    token = os.getenv("GITHUB_TOKEN")
+    if not token:
+        raise click.ClickException(
+            click.style("GITHUB_TOKEN environment variable is required", fg="red")
+        )
+
+    _ensure_ai_key_configured("use generate-releases")
+
+    log.info("checking repositories for release readiness")
+
+    repo = extract_repo_reference_from_github_url(repo)
+
+    if repo:
+        g = Github(token)
+        result = check_repo_for_release(g.get_repo(repo), dry_run)
+        if result["created"]:
+            log.info("release check complete - created 1 release", dry_run=dry_run)
+        elif result["failed"]:
+            log.info(
+                "release check complete - failed to create release", dry_run=dry_run
+            )
+        else:
+            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:
+        if max_releases > 0 and created_count >= max_releases:
+            log.info(
+                "reached max releases limit for this run",
+                max_releases=max_releases,
+            )
+            break
+
+        res = _check_repo_with_log(r)
+        results.append(res)
+        if res["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,
+        )
+
+
+cli.add_command(dependabot)
+cli.add_command(keep_alive_prs)
+cli.add_command(notifications)
+cli.add_command(generate_releases)
+
+if __name__ == "__main__":
+    cli()

github_overlord-0.9.1/github_overlord/ai.py

@@ -0,0 +1,69 @@
+"""AI agent configuration for github-overlord."""
+
+import os
+from typing import Any
+
+from pydantic_ai import Agent, ModelSettings
+
+DEFAULT_MODEL = "google:gemini-3.8-flash"
+
+
+def normalize_model_name(model_name: str) -> str:
+    """Ensure provider prefix is present for shorthand model names."""
+    cleaned = model_name.strip()
+    if ":" in cleaned or "/" in cleaned:
+        return cleaned
+    if cleaned.startswith("gemini"):
+        return f"google:{cleaned}"
+    if cleaned.startswith(("gpt", "o1", "o3")):
+        return f"openai:{cleaned}"
+    if cleaned.startswith("claude"):
+        return f"anthropic:{cleaned}"
+    return cleaned
+
+
+def resolve_model_name(model: str | None = None) -> str:
+    """Resolve and normalize active model name from argument, env vars, or default."""
+    raw_model = model or os.getenv("GITHUB_OVERLORD_MODEL") or DEFAULT_MODEL
+    return normalize_model_name(raw_model)
+
+
+def get_expected_ai_key_var(model: str | None = None) -> str:
+    """Return the expected environment variable name for the active model provider."""
+    selected_model = resolve_model_name(model)
+    provider = selected_model.split(":")[0] if ":" in selected_model else "google"
+    return (
+        "GOOGLE_API_KEY"
+        if provider in ("google", "gemini")
+        else f"{provider.upper()}_API_KEY"
+    )
+
+
+def is_ai_key_configured(model: str | None = None) -> bool:
+    """Check if an API key is configured for the active model provider."""
+    if os.getenv("GITHUB_OVERLORD_AI_KEY"):
+        return True
+    return bool(os.getenv(get_expected_ai_key_var(model)))
+
+
+def get_agent(
+    model: str | None = None,
+    output_type: Any = None,
+    system_prompt: str | None = None,
+) -> Agent[Any, Any]:
+    """Create a configured Pydantic AI Agent."""
+    selected_model = resolve_model_name(model)
+
+    # Map generic GITHUB_OVERLORD_AI_KEY to provider-specific env var if not already set
+    if generic_key := os.getenv("GITHUB_OVERLORD_AI_KEY"):
+        os.environ.setdefault(get_expected_ai_key_var(selected_model), generic_key)
+
+    kwargs: dict[str, Any] = {}
+    if output_type is not None:
+        kwargs["output_type"] = output_type
+    if system_prompt is not None:
+        kwargs["system_prompt"] = system_prompt
+    if selected_model.startswith("google:"):
+        kwargs["model_settings"] = ModelSettings(thinking="low")
+
+    return Agent(selected_model, **kwargs)

{github_overlord-0.8.0 → github_overlord-0.9.1}/github_overlord/config.py

@@ -1,11 +1,15 @@
 """Configuration for github-overlord."""
+
 from pathlib import Path
 
 import jinja2
 
 # Set up paths
-ROOT_DIRECTORY = Path(__file__).parent.parent.resolve()
-DATA_DIRECTORY = ROOT_DIRECTORY / "data"
+PACKAGE_DIRECTORY = Path(__file__).parent.resolve()
+DATA_DIRECTORY = PACKAGE_DIRECTORY / "data"
+if not DATA_DIRECTORY.exists():
+    DATA_DIRECTORY = PACKAGE_DIRECTORY.parent / "data"
+
 RELEASE_ANALYSIS_PROMPT_TEMPLATE = DATA_DIRECTORY / "release_analysis_prompt.j2"
 
 # Jinja2 environment for templates
@@ -13,5 +17,5 @@ JINJA_ENV = jinja2.Environment(
     loader=jinja2.FileSystemLoader(searchpath=str(DATA_DIRECTORY)),
     autoescape=False,  # No HTML escaping needed for prompts
     trim_blocks=True,
-    lstrip_blocks=True
+    lstrip_blocks=True,
 )

github_overlord-0.9.1/github_overlord/data/release_analysis_prompt.j2

@@ -0,0 +1,50 @@
+You are analyzing commits for an open-source project to determine if a new release should be created.
+
+Consider these factors, in order of importance:
+
+1. Number of commits (more commits = more likely to release, but even 1-2 significant commits may warrant a release)
+2. Type of changes (features, bug fixes, refactoring, docs, tests, dependencies; new features and bug fixes are more likely to warrant a release)
+3. Impact of changes (major features vs minor tweaks)
+4. Time since last release (longer time = more likely, but do not weight this heavily)
+
+Guidelines for `decision`:
+
+- "yes" = clear value in creating a release (new features, important fixes, meaningful updates)
+- "no" = minimal changes (typos, minor docs, CI tweaks only)
+- "maybe" = borderline case (some value but not urgent)
+- For dependency updates: patch bump
+- For bug fixes: patch bump
+- For new features: minor bump
+- For breaking changes: major bump
+
+Guidelines for `release_notes`:
+
+- Write a markdown changelog suitable for a GitHub release
+- Use markdown headers, lists, and formatting
+- Be concise and avoid adjectives
+- Focus on user-facing changes and impacts. Do not include internal dev tooling, documentation, build system, package/dependency updates, etc updates.
+- Organize by type of change (Features, Bug Fixes, etc.) when there are more than a handful of changes.
+
+Example format:
+
+```markdown
+## What's Changed
+
+### Features
+- Added support for Python 3.12
+- New configuration option for custom timeouts
+
+### Bug Fixes
+- Fixed authentication bug when using OAuth tokens
+- Resolved memory leak in background worker
+
+### Performance
+- Improved commit analysis by 40%
+```
+
+Repository: {{ repo_name }}
+{{ last_release_info }}
+Number of commits: {{ commit_count }}
+
+Commits:
+{{ commit_summary }}