OSS Maintainer Copilot

English | 简体中文

Issue triage, pull request review summaries, release notes, and repository hygiene reports for open-source maintainers.

oss-maintainer-copilot is a dependency-light CLI and GitHub Action workflow for maintainers who want a repeatable first-pass review of repository activity. It turns GitHub issues, pull requests, merged PRs, and community files into a practical maintainer report: issue triage, PR risk, draft release notes, repository readiness, and recommended next actions.

It is intentionally useful without paid services. The MVP uses deterministic rules and GitHub data only, so projects can run it in CI without sending repository data to a third-party model. Optional AI-assisted summaries can be added later without replacing the local analyzer.

Use Cases

• Run a weekly GitHub Actions report before maintainer triage.
• Find possible security issues that should not sit in a public issue queue.
• Prioritize pull requests that touch CI, auth, permissions, lockfiles, or other sensitive paths.
• Draft release notes from merged pull requests.
• Check whether a repository has the community files that make outside contribution easier.
• Produce JSON output for dashboards, bots, or future AI-assisted maintainer workflows.

Why It Exists

Small maintainers still carry serious responsibilities: issue triage, pull request review, release notes, contributor guidance, and security hygiene. This tool makes those workflows visible and repeatable.

It is also designed around maintainer workflows that programs like Codex for Open Source care about: PR review, issue triage, release workflows, security/code-quality checks, and evidence of active maintenance.

How It Is Different

Most tools in this space solve one slice: changelog generation, label automation, issue routing, or AI code review. oss-maintainer-copilot focuses on the maintainer's weekly operating view:

• It combines issue triage, pull request risk, release notes, and repository readiness in one report.
• It explains why an item was flagged instead of only assigning a label.
• It works from an offline JSON snapshot or GitHub REST API.
• It has no runtime dependencies and no required AI provider.
• It can become an AI-assisted workflow later without locking users into one model or hosting service.

Features

• Classifies open issues into bug, feature, docs, question, maintenance, and possible-security categories.
• Scores open PRs as low, medium, or high risk.
• Flags large churn, draft PRs, sensitive paths, CI failure/pending state, and missing tests.
• Drafts release-note sections from recently merged PRs.
• Builds a maintainer action queue with next steps and suggested reply templates.
• Checks repository readiness: README, license, contributing guide, security policy, CI, issue templates, PR template, and recent activity.
• Outputs Markdown for maintainers and JSON for automation.
• Runs from a local JSON snapshot or directly from GitHub REST API.
• Ships with a GitHub Actions workflow example.

Install

For local development:

npm install
npm test

Run the CLI from this checkout:

node bin/oss-maintainer-copilot.js audit --input examples/snapshot.json

After publishing to npm, the expected usage is:

npx oss-maintainer-copilot audit --repo owner/project

Quick Demo

git clone https://github.com/woshishadowhunter/oss-maintainer-copilot.git
cd oss-maintainer-copilot
npm install
node bin/oss-maintainer-copilot.js audit --input examples/snapshot.json

The demo prints a Markdown maintainer report with sections for repository readiness, issue triage, PR risk, a maintainer action queue, draft release notes, and recommended maintainer actions.

Read the full generated example: docs/demo-report.md.

Real repository reports generated by this project:

• lianxin-medicine-garden
• alaya-protocol

CLI Usage

Use an offline snapshot:

oss-maintainer-copilot audit --input examples/snapshot.json

Fetch from GitHub:

oss-maintainer-copilot audit --repo owner/project --token "$GITHUB_TOKEN"

Emit JSON:

oss-maintainer-copilot audit --input examples/snapshot.json --format json

Snapshot Format

{
  "repository": {
    "full_name": "owner/project",
    "description": "Project description",
    "stargazers_count": 12,
    "forks_count": 3,
    "open_issues_count": 8,
    "pushed_at": "2026-07-15T00:00:00Z"
  },
  "files": ["README.md", "LICENSE", "CONTRIBUTING.md", "SECURITY.md", ".github/workflows/ci.yml"],
  "issues": [],
  "pulls": [],
  "mergedPulls": []
}

Issue and PR objects follow common GitHub REST fields. Pull request objects may include files, changed_files, additions, deletions, draft, labels, and check_state.

Use As A GitHub Action

For the fastest repository setup, add this workflow to another repository:

name: Maintainer Copilot

on:
  workflow_dispatch:
  schedule:
    - cron: "0 8 * * 1"

jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      pull-requests: read
      checks: read
    steps:
      - uses: woshishadowhunter/oss-maintainer-copilot@v0.3.0
        with:
          token: ${{ github.token }}
          output: maintainer-report.md
      - uses: actions/upload-artifact@v4
        with:
          name: maintainer-report
          path: maintainer-report.md

The Action writes the Markdown report to the job summary and exposes outputs for readiness-score, urgent-actions, high-risk-prs, and report-path.

GitHub Actions From Source

The repository includes .github/workflows/maintainer-copilot.yml as a starting point. It runs the audit weekly and uploads the Markdown report as an artifact.

name: Maintainer Copilot

on:
  workflow_dispatch:
  schedule:
    - cron: "0 8 * * 1"

jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      pull-requests: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: node bin/oss-maintainer-copilot.js audit --repo "$GITHUB_REPOSITORY" > maintainer-report.md
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - uses: actions/upload-artifact@v4
        with:
          name: maintainer-report
          path: maintainer-report.md

Roadmap

• Optional OpenAI-powered natural-language summaries behind OPENAI_API_KEY.
• PR comment mode for maintainers who want a bot-authored risk summary.
• SARIF or Code Scanning output for security-sensitive repository hygiene checks.
• Multi-repository dashboard snapshots for maintainers who own several projects.
• Label sync suggestions with a dry-run mode.
• One-command export of the maintainer action queue into issue comments, project items, or saved triage notes.

Related Project Categories

This project is meant to sit between several existing GitHub automation categories:

• Issue triage automation
• Pull request review automation
• Release notes and changelog generation
• GitHub Action maintainer workflows
• Repository health and community-file checks
• Agent-ready OSS maintenance workflows

See docs/discovery-and-positioning.md for the positioning notes used to shape the README and roadmap.

Development

npm test
npm run check
npm pack --dry-run

Contributing

Contributions are welcome when they improve maintainer workflows without making the MVP harder to run. Start with CONTRIBUTING.md.

Security

Please do not open public issues for sensitive vulnerabilities. See SECURITY.md.

License

MIT