PR bot

The Repowise PR bot is a GitHub App that runs the same intelligence layers as the CLI and dashboard against every pull request. It posts one short comment, with a checks section when coverage, security or docs have something to say, optional pass/fail checks a branch rule can require, and review threads on the lines that need them. Every push gets a Repowise review check with the commit it reviewed and its finding counts. In Signals, the default mode, the comment is deterministic and posts only when there is something worth saying: no model, no per-PR tokens, and free forever for public / OSS repos. AI review adds a model on every pull request that changes code and is part of Pro, billed from credits. Private repos need the Pro plan too. See review modes.

Install#

Permissions requested: Contents: Read · Pull requests: Write · Metadata: Read · Issues: Write (GitHub treats PR comments as issue comments) · Checks: Write, for the Repowise review check, the merge gate, pass/fail checks and annotations on lines. Grant Checks: Write: without it the bot still comments, but a clean pull request gets no comment, so nothing on it shows the review ran. The one-click coverage setup needs Contents: Read and write and Workflows: Read and write.

Review modes#

The org policy picks the mode for every repo in an installation, and a repo can override it (Settings → PR bot). The mode is set only on the dashboard: the bot ignores review_mode in .repowise/bot.yaml, so a pull request from a fork cannot turn on a paid pass.

How AI review works#

• Quick pass on every push. A model reads the diff with the evidence Signals already computed: callers, co-change partners, findings, tests.
• Fix pushes are incremental. A later push is read for what changed since the last reviewed commit. The review remembers its earlier points, so a point is never raised twice, and a point whose lines a push fixed is resolved on its thread.
• A verifier on risky claims. A claim that a caller breaks, a failure is silently swallowed, or a high-priority logic error is checked against the code before it posts.
• A deep review when the change warrants it. On a risky pull request, where change risk, blast radius or hotspot history call for it, a deeper review reads the code around the diff. It runs automatically once per pull request, and on demand with depth deep or /repowise review deep.
• Tests in one thread. Changed code that no test reaches is listed once, in a single "Tests for this change" thread, edited in place as pushes land.
• Drafts. A draft pull request gets the quick pass. The deep review is considered when it is marked ready for review.
• On demand. Comment /repowise review deep to run the deep review on the current commit.

Depth (review_depth) sets how far AI review goes:

AI review draws on the same credit balance as chat, docs and MCP, with no per-seat review fee. Pro includes $5 of credits a month, about 55 reviewed pull requests, and 100 pull requests cost about $9. Two caps bound the spend: each pull request has a cap (ai_pr_cap_cents, 60 cents by default) and each repository a monthly AI spend limit ($5 by default). When the plan does not include AI review, the balance is empty, or the monthly limit is reached, the bot posts only what Signals would, and the comment and the review check note the pause. When a pull request's own cap is spent, later pushes get Signals and the review check says the pull request's AI budget is spent.

When the bot comments#

In Signals the bot stays silent unless there is a measurable signal worth interrupting a reviewer for. A pull request with no findings gets no comment at all. In AI review it also comments when the review has a point to raise. A clean quick pass posts no comment, and a clean deep review posts a short note that there is nothing to fix. Either way the Repowise review check reports every push, so a clean result is visible without a comment. When the bot does comment, improvements are shown alongside problems so cleanup gets credit. Signals posts when any of these fire:

• net repo health degrades, or any modified file's score drops;
• a hotspot file (high churn + many dependents) is touched;
• a top co-change partner of a modified file is missing from the PR;
• new dead code is introduced (or removed, which is a win);
• a modified file is on a declining-health trajectory;
• a changed file carries substantial recent bug-fix history;
• the diff's change-risk score lands in this repo's high band.

The bot edits its existing comment when new commits land instead of posting a wall of duplicates. If nothing is left to say after an earlier comment, the stale comment is deleted.

What's in the comment#

The comment is short and leads with what the reviewer should do. Each part renders only when it has something to say, and the full analysis is one click away: the View on Repowise button opens the pull request's page (/pr/{owner}/{repo}/{number}), and each review thread has a Details link to its point on that page.

Coverage, security, tests and doc drift form the comment's checks section (see checks). In Signals nothing in the comment is written by a model, so every comment is reproducible. AI review writes its part with a model, and the pull request page names the model that wrote it.

Findings on lines#

on_lines decides what lands on the changed lines themselves:

AI review points on code this PR wrote are capped by the review sensitivity.

The Repowise review check#

Every push gets a GitHub check run named Repowise review. It is on by default, and it tells people and coding agents whether the latest commit has been reviewed and what the review found:

The title ends with the depth that ran, shown as a tier label: (T1) for the quick pass, up to (T3) for the deep review. A run paused for credits or the plan is a normal clean or findings run with a note line in its summary. The summary names the reviewed commit and the base it was compared against. The check concludes failure only when the merge gate is on and blocking. Keep it out of required checks unless the gate is on.

For coding agents. The latest commit is reviewed when the Repowise review check on the head SHA is completed. Read the check's finding counts instead of comparing comment timestamps. When the bot posts a comment, its hidden repowise-bot marker also carries the reviewed head SHA. A clean pull request gets no comment, so on an install without Checks: Write there is nothing to read: grant it.

To turn the check off for a repo, set review_check: false.

Commands#

Comment on a pull request:

Put [skip repowise] in a pull request title to skip it.

Teach the review#

Reply on one of the review's findings to tell it what your team does, for example "we validate this at the API boundary, not here". The review saves the reply as a decision and applies it to later reviews, and answers on the thread with what it saved and a link to it.

• Write access accepts it. A reply from someone with write, maintain or admin access on the repository is accepted right away: "Saved as a decision (accepted: octocat has write access)". Anyone else's reply is saved for someone to accept.
• Accept from the thread. Reply /repowise confirm on the thread to accept a saved decision, or confirm it on the repository's Decisions page.
• Undo. Reply /repowise forget on the thread. The decision stops shaping reviews, and a finding the reply had quieted can be raised again.

The Learn from replies setting, in a repository's bot settings or the org policy, picks what a reply becomes:

What the review learned on a repository is listed under What it learned from your team in that repository's bot settings. Teammates who did not install the bot can see it there; only the person who installed the bot can change the setting.

The merge gate#

Beyond commenting, the bot can post a GitHub Check Run named Repowise / code health that a branch protection rule can require, turning code health into a merge gate. It is off by default (health_gate.mode):

• off: no check is created.
• advisory: always concludes neutral. The verdict is visible on the PR but never blocks. The safe default to start with.
• blocking: concludes failure when a rule trips, which a required check will block the merge on.

The rules (evaluated only in blocking mode):

Or start from a named profile and nudge single knobs: health_gate.profile accepts warn-only, block-new-file-floor or block-any-decline. The profile seeds the rules; any explicit key set alongside it wins.

not_evaluated decides what every Repowise check run concludes when it could not evaluate, for example no health score yet or no coverage report: neutral (the default) passes a required check, failure holds the merge until it can evaluate.

Checks#

The comment's checks section carries what the tests, the security scan and the docs say about the change (see what's in the comment). checks_comment decides when it renders:

• on_signal (the default): only when a check has something to say. Once shown it is always updated, to an all-clear line when the findings are gone, so a stale finding never lingers.
• always: on every pull request.
• off: never.

Pass/fail checks#

Each check can also post its own GitHub check run, which a branch protection rule can require. check_runs lists the ones that run. review (the Repowise review check) is on by default, the rest are off, and all work with or without the checks section:

A check that could not evaluate concludes as not_evaluated says.

Coverage setup#

Measured coverage needs a coverage report from your CI. In the dashboard (Settings → PR bot → a repo's settings → Checks), Set up coverage has the bot open a draft pull request that adds .github/workflows/repowise-coverage.yml: it runs your tests with coverage and uploads the report with the step below. The bot detects the stack (Python, Node, Go, Java with Maven or Gradle) and the pull request says how to adjust the test command. If your tests already run in another workflow, it explains how to move the upload step there so they run once. Review it, mark it ready and merge it; the next pull request carries a coverage line.

The one-click setup needs two extra repository permissions on the PR bot: Contents: Read and write and Workflows: Read and write. Existing installs see "Approve the new permission" in the dashboard, which links to the installation's settings on GitHub. Everything else (the checks section, check runs, uploads) works without them.

Or add it yourself. The dashboard shows the generated workflow, and the upload step alone, to copy. Add the step to the job that runs your tests, after the step that writes the coverage report, and give the job the id-token: write permission:

jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write   # lets the upload prove it comes from this repository
    steps:
      # ... check out, install, and run your tests with coverage ...
      - name: Upload coverage to Repowise
        if: always()
        continue-on-error: true
        env:
          REPORTS: "coverage.xml"   # space-separated paths or globs
          HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        run: |
          shopt -s globstar nullglob
          files=()
          for pattern in $REPORTS; do for f in $pattern; do [ -f "$f" ] && files+=(-F "report=@$f"); done; done
          if [ ${#files[@]} -eq 0 ]; then echo "::warning::Repowise: no coverage report found at: $REPORTS"; exit 0; fi
          auth=()
          if [ -n "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ]; then
            token=$(curl -sS -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=repowise" | jq -r '.value // empty' || true)
            [ -n "$token" ] && auth=(-H "Authorization: Bearer $token")
          fi
          curl -sS --fail-with-body --max-time 60 "${auth[@]}" "${files[@]}" \
            -F "repository=$GITHUB_REPOSITORY" -F "head_sha=$HEAD_SHA" -F "pr_number=$PR_NUMBER" \
            -F "event=$GITHUB_EVENT_NAME" -F "run_url=$RUN_URL" -F "workspace=$GITHUB_WORKSPACE" \
            https://api.repowise.dev/ci/coverage \
            || echo "::warning::Repowise: coverage upload failed; see the message above."

It is plain curl and jq, so it needs no extra action. It never fails the job: a missing report or a failed upload is a warning in the log, and the server's answer (including how many report paths did not match a file in the repository) is printed there too.

REPORTS is a space-separated list of report paths or globs (** works), relative to the repository root. Supported formats: LCOV, Cobertura XML, JaCoCo XML, Clover XML, Go coverprofile, and the Repowise coverage JSON. The format is detected from each file, and absolute paths in a report are made relative to the checkout. Typical values:

Runners. GitHub-hosted runners have curl and jq installed. Self-hosted runners need curl and jq; without jq the upload has no identity and is refused.

Fork pull requests. The upload proves which repository it comes from with a short-lived identity token from the workflow, so no secret is needed. A pull request from a fork gets no such token. Its upload is accepted only when the repository is public and the upload is for the open pull request's current head commit; the comment then labels it "uploaded from a fork pull request without verified identity". Such an upload never replaces a verified one for the same commit. On a private repository, fork uploads are refused.

Getting coverage into hosted#

Measured coverage reaches a repo's Tests page and the hosted MCP tools by one of two routes. Both read the same report formats your test runner already writes.

Formats. The manual upload takes LCOV, Cobertura XML, Clover XML, the Repowise coverage JSON, and a coverage.py .coverage file. The CI upload takes the formats listed under REPORTS above, plus a .coverage file.

Default-branch pushes fill the Tests page. Only an upload from a push to the default branch reaches the Tests page and the MCP tools. Uploads from pull request runs feed the pull request coverage check and nothing else, so run the coverage job on both events:

on:
  push:
    branches: [main]   # your default branch
  pull_request:

The job needs permissions: id-token: write (and contents: read) so the upload can prove which repository it comes from.

Per-test map. Knowing which tests to run for a change needs a report that records which test covered each line. Produce it with pytest --cov=<package> --cov-context=test (needs pytest-cov), which writes a .coverage file, or as an LCOV report where each block carries a distinct TN: test name. See Building a per-test map.

Send it either way:

• Manual upload on the repo's Tests page.
• CI upload from a push run on the default branch, with .coverage in REPORTS (the step sends it as -F report=@.coverage). The workflow the bot generates for a Python project sends it on push.

Pull request runs give totals for the pull request check only, even when they send .coverage.

Where it shows. The Tests page shows per-file and per-module coverage, untested hotspots, and the risk-versus-coverage view. Through the hosted MCP, get_risk returns tests_to_run and get_change_risk lists impacted tests, both from the per-test map.

Checks settings#

Configuration#

Settings come from layers, lowest first; a higher layer wins for each key it sets:

1. the bot's defaults;
2. the org policy of the installation;
3. .repowise/bot.yaml in the repo;
4. the repo's own settings on the dashboard;
5. the keys the org policy locks.

Policy keys decide a gate, so a pull request cannot loosen them from its own branch: health_gate, check_runs, coverage_fail_under, security_fail_on, not_evaluated, review_check, ignore_paths and apply_labels are read from .repowise/bot.yaml on the base branch only. Paid keys (review_mode, review_depth, ai_pr_cap_cents, ai_monthly_cap_cents) are read from the dashboard only. ignore_paths is a union across layers, so a layer can add scope but never un-ignore a path another layer skips. A malformed value is skipped and the layer below stands.

Org policy and repo overrides#

Settings → PR bot → an installation opens its org policy: the settings every repo it covers starts from. It offers three presets:

No preset changes the review mode, which is a paid choice of its own. The page shows how many repos follow the preset (override none of its keys), and can make selected repos follow it: after a confirmation naming the repos and the settings, it clears their overrides of the preset's keys and leaves the rest.

Each policy row has a lock. A locked key wins over the repo's dashboard settings and its .repowise/bot.yaml, so a repo cannot loosen it; the repo's page shows the row read only. Locking a key the policy does not set yet pins the value the repos get at that moment. The merge gate locks as one key.

A repo's page (Customise on the policy, or Settings on a repo row) shows every setting with its value and where it comes from: Default, Org default, Overridden or Locked by org. A change there overrides the policy for that repo; Reset on a row, or Reset all to org default, removes the override. The dashboard cannot see .repowise/bot.yaml, so a value marked Default or Org default may still be changed by the repo's YAML.

.repowise/bot.yaml#

Committed and versioned with the code:

bot:
  enabled: true
  comment_mode: on_signal      # or "always" to post a clean bill of health
  verbosity: standard          # compact | standard
  introduced: high             # off | show | critical | high | medium | low
  recent_decline: show         # same values; "show" never posts on its own
  change_risk: signal          # off | signal (PR page) | comment
  on_lines: threads            # off | annotations | threads | both
  apply_labels: false          # opt in to repowise:* PR labels
  ignore_paths:
    - "vendor/**"
    - "**/*.generated.*"
  health_gate:
    mode: advisory             # off | advisory | blocking
    repo_drop_block: 0.3
    min_new_file_score: 7.0
    block_on_introduced: true
    block_at: high
  checks_comment: on_signal    # off | on_signal | always
  check_runs: [review, coverage]  # review | coverage | security | doc_drift
  coverage_fail_under: 80      # percent of changed lines; omit to report only
  not_evaluated: neutral       # neutral | failure

The comment's parts each have a switch: show_health, show_checklist, show_coupling, show_ownership, show_evidence and show_declining_alert. Pre-v2 key names (show_introduced with introduced_posts_at, inline_threads, show_findings_on_lines, coverage_check_run, checks_comment_mode and the rest) still read into the key they became.

PR labels (opt-in)#

With apply_labels: true the bot also applies repowise:* labels, created on demand and reconciled on every run: a label is removed once its signal clears, and labels outside the repowise: namespace are never touched.

They are off by default, and the list is short on purpose. A label is permanent, binary, and public in the pull-request list, so it reads as a verdict on the author in a way an editable comment does not, which means it has to be reserved for things that are actually rare. Signals that fire on ordinary work (a repo score that dipped, a hotspot touched, a moderately-sized diff) stay in the comment, where they carry their context with them.

Pricing#

Signals is free forever for public / OSS repos: no model, no tokens, no PR cap. AI review is part of Pro and billed from credits, about 9 cents a pull request on average (see review modes). Private repos require the Pro plan as well. Private installs still index on connect, so the snapshot is ready when you upgrade. See the pricing page.

How it relates to the rest of Repowise#

Same engine, different surface. The bot reads the code-health, git-intelligence, and dependency-graph layers, and every comment links to the pull request's page on the dashboard, where the same data is queryable by humans (the web UI) and by AI agents (the MCP tools, including get_health for a pre-PR self-check).