91 lines
5.1 KiB
Markdown
91 lines
5.1 KiB
Markdown
# RepoPulse
|
|
|
|
**Explain repository health, maintenance risk and release readiness from local, deterministic evidence.**
|
|
|
|
RepoPulse is a self-hosted Gitea repository intelligence dashboard. It scans exact revisions, keeps findings and history, and helps prioritize the next maintenance action. Source code is analyzed locally without sending it to an external model.
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
A[Gitea catalog / local path] --> B[Exact revision acquisition]
|
|
B --> C[Bounded deterministic scan]
|
|
C --> D[Findings and explainable scores]
|
|
D --> E[Portfolio / remediation / history]
|
|
```
|
|
|
|
## Capabilities
|
|
|
|
- Read-only Gitea repository discovery, default-branch reconciliation and optional signed push webhooks.
|
|
- Durable SQLite job queue, revision deduplication, lease recovery and detached scan worktrees.
|
|
- Repository portfolio, triage, quick switch, architecture, hotspots, findings and history views.
|
|
- Language/LOC inventory, test/CI signals, dependency and lockfile analysis across common ecosystems.
|
|
- TODO debt, bounded churn, local import graphs and explainable hotspot ranking.
|
|
- Redacted credential-assignment warnings and backend-owned remediation guidance.
|
|
- Transparent scan budgets and truncation metadata instead of overstating scan coverage.
|
|
- Accepted-risk policies, release gates, finding deltas and standalone HTML/JSON reports.
|
|
|
|
## Interface preview
|
|
|
|
These screenshots show the deterministic browser-test fixture: fictional Alpha/Beta/Gamma repositories, not a private or live repository inventory.
|
|
|
|
|
|
|
|
|
|
|
|
## Deploy
|
|
|
|
```bash
|
|
git clone https://gitea.itworx.tech/Jens/RepoPulse-Public.git
|
|
cd RepoPulse-Public
|
|
cp .env.example .env
|
|
# Select the intended repository directory and configure your Gitea connector.
|
|
docker compose up --build
|
|
```
|
|
|
|
Open `http://localhost:1254`. Compose runs a Python API and React frontend. `REPOPULSE_SOURCE_ROOT` defaults to the parent directory and is mounted read-only at `/scan`; narrow it to the repository collection you intend to inspect. The Advanced path flow accepts paths inside that boundary.
|
|
|
|
`REPOPULSE_DATA_ROOT=./data` in the local template retains SQLite history, queue and repository mirrors. If unset, Compose uses the named `repopulse_data` volume. Keep persisted data outside a replaceable checkout and back it up before upgrades. The durable queue intentionally runs one active scan worker.
|
|
|
|
## Connect Gitea
|
|
|
|
Configure these values on the server, never in the frontend:
|
|
|
|
```dotenv
|
|
REPOPULSE_GITEA_URL=https://gitea.example.test
|
|
REPOPULSE_GITEA_TOKEN=<repository-read-token>
|
|
REPOPULSE_OPERATOR_TOKEN=<independent-operator-token>
|
|
```
|
|
|
|
Use only the repository-read permissions needed for the intended catalog and revisions. An optional `REPOPULSE_GITEA_WEBHOOK_SECRET` authenticates push notifications. RepoPulse discovers repositories, resolves revisions, queues stale work, scans exact SHAs and retains results by revision. Incomplete or failed discovery preserves existing evidence rather than silently declaring missing repositories unavailable.
|
|
|
|
Protect deployment with an authenticated proxy or configure `REPOPULSE_OPERATOR_TOKEN`; the mutation API uses `X-RepoPulse-Token`. Limit network access and the scan mount. Direct development without `REPOPULSE_SCAN_ROOT` can read any path accessible to that process.
|
|
|
|
## Interpret results
|
|
|
|
Findings are deterministic observations with locations and severity. Health scores reflect documented deductions; release gates report **READY**, **READY WITH WARNINGS** or **BLOCKED** under repository policy. Remediation guidance explains confidence, priority and a suggested first action. RepoPulse never edits external repositories automatically.
|
|
|
|
Heuristics are engineering guidance, not a substitute for review, runtime tests or specialized security audits. Truncated scans expose their limits. Credential warnings redact values but still require human investigation. Repository history and retained reports contain source-derived metadata, so treat the persisted store as sensitive.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
# Activate .venv for your shell.
|
|
pip install -r requirements.txt
|
|
uvicorn app.main:app --app-dir backend --reload --port 8000
|
|
```
|
|
|
|
In another terminal:
|
|
|
|
```bash
|
|
npm --prefix frontend ci
|
|
npm --prefix frontend run dev
|
|
```
|
|
|
|
Run `python -m pytest`, `npm --prefix frontend test`, `npm --prefix frontend run typecheck` and `npm --prefix frontend run build`. The browser test fixture uses deterministic API responses; it is not a live production portfolio. See [architecture](docs/ARCHITECTURE.md) for implementation detail.
|
|
|
|
## Source distribution and licensing
|
|
|
|
This is the curated public source edition of RepoPulse 1.5.0. Reviewed updates flow from the private canonical repository after merges to `main`, without private history, repository inventories, runtime stores or internal CI/deployment workflows. Configure the generic deployment templates for your own environment.
|
|
|
|
No project-wide license is included. Public visibility does not grant reuse or redistribution rights; obtain the owner's terms and review third-party dependencies before redistribution.
|