← back

RepoWave — Documentation

RepoWave is a GitHub App that audits Python, FastAPI, GitHub Actions, and Dockerfiles on every push, and opens draft Pull Requests for fixes that are safe to apply unattended (formatting, import order).

Install

  1. Go to the approved GitHub Marketplace listing and click Add.
  2. Choose the account (personal or organization) to install on.
  3. Pick All repositories or select specific ones.
  4. Click Install.

After install, RepoWave receives an installation webhook from GitHub and creates a tracking row for your account. No action is taken until you push code.

What happens on each push

Every push to any branch triggers a scan of that commit:

  1. Webhook intake — the push event is signature-verified and persisted as a scan job.
  2. Tarball clone — RepoWave downloads the commit's source tree via the GitHub API using the installation token. The clone is ephemeral and deleted at scan end. No source is persisted.
  3. Static analysis — rules run across Python, FastAPI routes, GitHub Actions workflows, and Dockerfiles. See Rules below.
  4. Commit comment — a summary table is posted on the commit's GitHub page: rule, severity, message, location.
  5. Autofix (if eligible) — for findings whose fix category is allow-listed (formatting, import order), RepoWave runs ruff on the affected files in the clone, then opens a draft Pull Request against your default branch with one commit applying the fix.

Median end-to-end latency: 5–10 seconds for repos under 50 MB.

Rules

| Category | Examples | |---|---| | Python dead code | unused imports, unused functions, unused classes, unreachable blocks | | Python async safety | mixing blocking I/O inside async def | | Python HTTP timeouts | requests.get(...) without timeout= | | Python logging hygiene | log.exception(...) discouraged, structured logging preferred | | Python Pydantic compat | v1 / v2 mixed usage | | FastAPI quality | untyped returns, missing response_model, direct DB access in routes | | GitHub Actions hygiene | unpinned action versions, missing permissions blocks, dangerous patterns | | Docker quality | running as root, missing HEALTHCHECK, layer-cache hygiene |

Each rule reports a finding with severity (critical, high, medium, low, info), confidence (0.0–1.0), file path, and line number.

What autofixes look like

A draft PR titled [RepoWave] Apply N safe autofix(es):

You can safely close the PR if you disagree. RepoWave will not reopen it.

What RepoWave never reads

A hardcoded denylist (core/security/autofix_gate.py) excludes:

This list cannot be overridden by configuration or feature flags. Files in these paths are not read, not scanned, and not eligible for autofix.

Configuration

For local CLI scans, RepoWave reads <repo>/repowave.toml when it exists. The supported fields are:

[scan]
min_severity = "low"
fail_on = "critical"
rules = ["actions.hygiene.unpinned_action"]

CLI flags override the file. Use repowave scan <path> --config <file> to point at a config file outside the repo root.

The hosted GitHub App does not support per-repository configuration today. App defaults are conservative and identical across installations.

Local CLI development

When testing a source checkout as a global CLI, prefer an editable uv tool install:

uv tool install --editable . --force
repowave version

If you need a non-editable source install, use uv tool install --force --reinstall .. A plain forced install can reuse a cached wheel when the package version has not changed.

Future hosted-app config:

Uninstall

  1. Go to your GitHub Settings → Applications → Installed GitHub Apps.
  2. Find RepoWaveAudit → Configure → Uninstall.

Per our Privacy Policy, all data associated with the installation is hard-deleted within 30 days. Open audit-log entries (github_write_audit) are deleted with the installation row via foreign-key cascade.

Self-host

The same analysis runs locally for pre-push checks. Contact support@repowave.dev for self-hosting access.

Troubleshooting

The scan ran but no commit comment appeared. Verify: the commit was on a branch (not a tag), the App is still installed on the repo, the App has Contents and Pull-requests write permission. The commit comment is best-effort — if our repo.create_comment(...) call fails the scan is still recorded.

The draft PR opened but I want to disable autofixes. Today: close the PR. Future: per-repo opt-out flag.

I see a finding I disagree with. RepoWave does not block your build. Findings are informational unless you wire them into a check. Open an issue at support@repowave.dev with the rule ID and a reproduction.

Limits

Support

Email: support@repowave.dev

For security disclosures, prefix the subject with SECURITY: and we will respond within four hours.