MaintainerLens

AI-assisted issue and PR triage for small open-source maintainers.

MaintainerLens is a GitHub Action and Python CLI that helps small open-source maintainers triage issues and prepare pull request reviews. It detects missing reproduction details, test gaps, risky PR changes, suggested labels, and posts maintainer-friendly comments directly on GitHub.

It is for maintainers who do not need a SaaS dashboard, queueing system, or required AI API key. MaintainerLens runs in GitHub Actions or locally, uses deterministic rules by default, and produces review notes that a maintainer can verify quickly.

MaintainerLens issue triage

Type: Bug report
Completeness: 60/100
Risk: High

Missing information:
- Reproduction steps
- OS/environment
- Minimal example

Suggested labels:
bug, needs-info, needs-repro, high-risk

Install As A GitHub Action

name: MaintainerLens

on:
  issues:
    types: [opened, edited]
  pull_request:
    types: [opened, synchronize, reopened, edited]

permissions:
  contents: read
  issues: write
  pull-requests: read

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: tanayv77/MaintainerLens@v0.1.0
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

MaintainerLens intentionally avoids recommending pull_request_target by default. If maintainers use it, they should understand the security implications and avoid running untrusted pull request code with privileged tokens.

CLI Quickstart

pip install -e ".[dev]"

maintainerlens issue examples/issue_bug.json
maintainerlens pr examples/pr_small.json
maintainerlens scan .

You can also run without relying on the installed console script:

python -m maintainerlens issue examples/issue_bug.json
python -m maintainerlens pr examples/pr_small.json
python -m maintainerlens scan .

Example Issue Comment

<!-- maintainerlens -->
## MaintainerLens triage

**Type:** Bug
**Completeness:** 60/100
**Risk:** High
**Likely area:** cli

### Maintainer summary
This looks like a bug touching cli. The report is missing reproduction steps, OS/environment, minimal example, so a maintainer may need clarification before acting.

### Missing information
- reproduction steps
- OS/environment
- minimal example

### Suggested labels
`bug` `needs-info` `needs-repro` `high-risk`

### Reporter checklist
- [ ] Add exact steps to reproduce
- [ ] Add OS/version details
- [ ] Add a minimal example or small reproduction

<sub>MaintainerLens is an automated maintainer-assistance tool. Please verify before acting.</sub>

Example PR Review-Prep Comment

<!-- maintainerlens -->
## MaintainerLens PR review prep

**Risk:** High
**Type:** Dependency
**Changed areas:** backend, security-sensitive, database, dependencies, config

### Summary
This looks like a dependency PR with 12 changed file(s) across backend, security-sensitive, database, dependencies, config. Current review risk is high.

### Review checklist
- [ ] Confirm behavior matches the issue/request
- [ ] Run tests
- [ ] Check edge cases
- [ ] Confirm docs/changelog are not needed or were updated
- [ ] Review security, permissions, migration, or data-loss implications
- [ ] Check lockfile and dependency trust implications

### Missing signals
- No test file changed
- No documentation update detected
- No changelog update detected

### Suggested labels
`medium-risk` `tests-needed` `docs-needed` `high-risk`

<sub>MaintainerLens helps prepare review, but it does not replace maintainer judgement.</sub>

What It Does

• Classifies issues as bug, feature request, documentation, question, security, or unclear.
• Scores issue completeness and identifies missing reporter information.
• Suggests labels such as bug, needs-info, needs-repro, tests-needed, and risk labels.
• Detects PR risk from file count, diff size, sensitive paths, test signals, docs/changelog updates, dependency changes, CI changes, lockfiles, and migrations.
• Scans a repository for maintainer-readiness signals such as README, license, security policy, tests, workflows, templates, changelog, docs, and dependency manifests.
• Creates or updates one GitHub comment using the hidden marker <!-- maintainerlens -->, so repeated runs do not spam the thread.

Why This Exists

Small maintainers often lose time turning incomplete reports and risky changes into a review plan. MaintainerLens gives the maintainer a first pass:

• Is this issue actionable?
• What information is missing?
• Does this PR touch risky areas?
• Are tests, docs, changelog, or dependency signals missing?
• What should I verify before responding or merging?

The output is intentionally advisory. It helps prepare review; it does not replace maintainer judgement.

Action Inputs

Input	Default	Description
github-token	required	Token used to create or update the MaintainerLens comment.
mode	auto	Reserved for future routing options.
comment	true	Set to false to render without posting.
dry-run	false	Set to true to avoid GitHub writes.
fail-on-risk	never	Use high, medium, low, or never.

CLI Commands

maintainerlens issue examples/issue_bug.json --out issue-report.md
maintainerlens pr examples/pr_small.json --out pr-report.md
maintainerlens scan .
maintainerlens action --event-path "$GITHUB_EVENT_PATH" --dry-run --no-comment

The CLI accepts GitHub-like JSON and normalizes common event payload shapes. See docs/demo.md for a fuller walkthrough.

How Scoring Works

Issue completeness starts at 0 and awards points for a meaningful title, useful body length, reproduction steps, expected and actual behavior, environment details, logs, version or commit, screenshots or links, and a minimal example.

PR risk increases when a change touches many files, has a large diff, modifies security-sensitive areas, changes build or dependency files, or changes code without tests. Docs-only and tests-only changes are usually low risk.

Repository scanning scores maintainer readiness out of 100 across README, license, contributing guide, security policy, tests, CI workflows, issue and PR templates, changelog, dependency manifests, docs, and .env.example when environment files are detected.

Security Notes

• MaintainerLens does not execute code from pull requests.
• The default workflow uses pull_request, not pull_request_target.
• Tokens are not logged.
• The GitHub token only needs limited permissions: contents: read, issues: write, and pull-requests: read.
• Comments are assistance, not authority. Maintainers should verify before acting.
• Future AI mode should be opt-in, privacy-aware, and clear about what content is sent to a model provider.

AI Mode

--ai exists as a placeholder and prints a clear note:

AI mode is not required. Deterministic triage is used by default.

No OpenAI calls are made today, no API key is required, and tests do not make external network calls.

Roadmap

See ROADMAP.md. Near-term work includes label configuration, PyPI publishing, better dependency update risk scoring, monorepo detection, and optional OpenAI-assisted summaries.

Contributing

This is an early-stage project. The useful work is reliable heuristics, careful tests, clear documentation, and security-conscious GitHub Action behavior. See CONTRIBUTING.md and AGENTS.md for development notes.