RepoPulse

RepoPulse is a Python CLI tool that scans GitHub repositories and produces a practical health report with a score out of 100, clear warnings, and actionable recommendations.

It is built for developers who want a quick repository quality review from the terminal, and for maintainers who want a small tool they can later run in CI.

Quick Links

• Arabic README
• Spanish README
• Installation Guide
• Usage Guide
• Requirements
• Supported Checks
• JSON report contract
• Architecture
• Contributing
• Security Policy
• Roadmap
• License
• Changelog
• Publishing guide
• Releases

Why RepoPulse Matters

Open source maintainers repeat the same repository hygiene checks across projects: README quality, licensing, CI, tests, stale activity, sensitive file names, and basic security posture. RepoPulse turns those checks into a quick, repeatable report that can run locally or in automation.

The project is early-stage, but it is designed around practical maintainer workflows: fast triage, clear recommendations, CI thresholds, and machine-readable output for future automation.

Features

• Scan public GitHub repositories by URL.
• Scan a local directory offline (repopulse scan .) without the GitHub API.
• Emit GitHub-issue-ready recommendations with --format issues.
• Scan private repositories with --token or GITHUB_TOKEN.
• Fetch repository metadata and recursive file tree through the GitHub API (remote scans).
• Score repository health out of 100.
• Render a Rich terminal report.
• Export Markdown reports.
• Print or write JSON reports.
• Produce compact summaries for automation.
• Fail CI jobs with --fail-under.
• Compare two scans (repopulse compare) with score/check deltas and --fail-on-regression.
• Drop-in GitHub Actions example for CI health gates (examples/github-action-repopulse.yml).
• Customize check weights and default thresholds with .repopulse.yml (optional named profiles: strict, library, docs, release).
• Detect common sensitive file names without printing secret contents.
• Add advisory dependency and security baseline recommendations.

Tech Stack

RepoPulse is built with:

Technology	Purpose
Python 3.11+	Core runtime.
Typer	CLI commands and options.
Requests	GitHub API calls.
Rich	Terminal tables and formatted output.
Pydantic	Typed report and check models.
python-dotenv	Optional GITHUB_TOKEN loading.
Pytest	Test suite.
Ruff	Linting in CI.

Installation

When published on PyPI:

pip install repopulse

Or clone and install from source:

git clone https://github.com/3ssiri/RepoPulse.git
cd RepoPulse
pip install -e .

For development:

pip install -e ".[dev]"

See INSTALLATION.md for full setup notes.

Basic Usage

repopulse scan .
repopulse scan https://github.com/username/repository
repopulse scan https://github.com/username/repository --export report.md
repopulse scan https://github.com/username/repository --format json --output report.json
repopulse scan https://github.com/username/repository --fail-under 75
repopulse scan https://github.com/username/repository --config .repopulse.yml
repopulse scan https://github.com/username/private-repo --token YOUR_GITHUB_TOKEN
repopulse compare ./checkout-main ./checkout-pr --fail-on-regression

You can also set a token in the environment:

GITHUB_TOKEN=YOUR_GITHUB_TOKEN repopulse scan https://github.com/username/private-repo

See USAGE.md for all options and examples.

OSS Maintainer Use Cases

• Run repository health checks before releases.
• Add a --fail-under threshold to CI for project quality gates (see examples/github-action-repopulse.yml and USAGE.md).
• Export Markdown reports for issue triage or maintainer handoff.
• Export JSON for dashboards, bots, or future AI-assisted review workflows.
• Audit public or private repositories without printing secret contents.

Example Output

RepoPulse Health Report for psf/requests
Score: 91 / 100 - Excellent

Checks
README Quality      PASS   16/20
License             PASS   10/10
.gitignore          PASS   10/10
Tests               WARN   12/15
GitHub Actions      PASS   15/15

Scoring System

Check	Points
README Quality	20
License	10
.gitignore	10
Tests	15
GitHub Actions	15
Recent Activity	10
Sensitive Files	10
Project Structure	5
Package Scripts	5

Grades:

Score	Grade
90-100	Excellent
75-89	Good
60-74	Fair
40-59	Weak
0-39	Critical

Dependency and security baseline checks are advisory in v0.1.0; they add recommendations without changing the 100-point score.

Configuration

RepoPulse automatically reads .repopulse.yml from the current directory when present. You can also pass a file explicitly:

repopulse scan https://github.com/username/repository --config examples/repopulse.yml

Configuration supports default CI thresholds, disabled checks, and custom weights:

fail_under: 85
disabled_checks:
  - activity
weights:
  readme: 25
  tests: 20
  github_actions: 20

See examples/repopulse.yml for a complete example.

Supported Checks

• README completeness.
• License presence.
• .gitignore presence and common patterns.
• Test folders, test files, and package test commands.
• GitHub Actions workflows for CI, tests, linting, and builds.
• Recent activity based on pushed_at.
• Sensitive file names such as .env, credentials.json, and private keys.
• Project structure and root clutter.
• Package scripts or Python project configuration.
• Dependency hygiene through lockfiles and Dependabot.
• Security baseline through SECURITY.md, Dependabot, and CodeQL.

Full details are in docs/checks.md.

Requirements

• Python 3.11 or newer.
• Network access to api.github.com.
• GitHub token for private repositories or higher API rate limits.

See REQUIREMENTS.md for runtime and development requirements.

Contributing

Contributions are welcome. Keep checks independent, return CheckResult, and add focused tests for new behavior.

See CONTRIBUTING.md for setup, testing, and contribution workflow.

License

RepoPulse is released under the MIT License. See LICENSE.