WuMing is a Woodpecker plugin to us AI Agents to perform reviews on pull requests
  • Python 98.7%
  • Just 0.6%
  • Shell 0.4%
  • Dockerfile 0.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-01 17:15:17 +10:00
.forgejo/workflows 🔧 Trust the agent account to settle findings on this repo 2026-10-20 18:23:09 +10:00
docs 🐛 fix: read the review policy from the default branch 2026-10-22 17:07:10 +10:00
src/wuming 🐛 fix: read the review policy from the default branch 2026-10-22 17:07:10 +10:00
tests 🐛 fix: read the review policy from the default branch 2026-10-22 17:07:10 +10:00
tools 🛡️ wrap pin verification errors and sanitize log values 2026-08-30 13:52:28 +10:00
.gitignore ⬆️ bump httpx2 and toolchain, pin vulnerable transitives 2026-10-15 19:13:16 +10:00
.pre-commit-config.yaml ⬆️ bump httpx2 and toolchain, floor filelock and virtualenv 2026-11-01 16:42:26 +10:00
.python-version 🔧 chore: pin dev venv to Python 3.14, pin tool nox sessions to MIN_PYTHON 2026-06-09 13:59:38 +10:00
action.yml ✨ Add WUMING_SETTLE_AUTHORS for delegating declines 2026-10-20 18:19:51 +10:00
AGENTS.md 📝 docs: review policy file reference 2026-10-22 16:28:42 +10:00
CHANGELOG.md 📝 docs: update changelog for 0.15.0 2026-10-22 19:30:57 +10:00
CLAUDE.md ⬆️ bump deps 2026-07-18 11:18:07 +10:00
Containerfile 🚚 Update source references from codeberg.org to forge.marvin8.zone 2026-08-06 13:04:18 +10:00
Improvements.md ⬆️ bump deps 2026-08-29 16:54:52 +10:00
justfile 🔧 remove missed dockerhub config 2026-08-06 14:10:41 +10:00
mkdocs.yml 📝 docs: review policy file reference 2026-10-22 16:28:42 +10:00
noxfile.py ♻️ Parse config.py env reads with ast, fix release-notes phrasing 2026-10-17 10:26:31 +10:00
pylock.toml ⬆️ bump httpx2 and toolchain, floor filelock and virtualenv 2026-11-01 16:42:26 +10:00
pyproject.toml ⬆️ bump httpx2 and toolchain, floor filelock and virtualenv 2026-11-01 16:42:26 +10:00
README.md 🐛 fix: read the review policy from the default branch 2026-10-22 17:07:10 +10:00
Release-Notes.md 📝 docs: review policy file reference 2026-10-22 16:28:42 +10:00
Release-Notes.md.template 🚚 Update source references from codeberg.org to forge.marvin8.zone 2026-08-06 13:04:18 +10:00
run-wuming.fish 🚚 Update source references from codeberg.org to forge.marvin8.zone 2026-08-06 13:04:18 +10:00
uv.lock ⬆️ bump httpx2 and toolchain, floor filelock and virtualenv 2026-11-01 16:42:26 +10:00
wuming.pub 🔑 add cosign public key for image verification 2026-08-31 06:42:44 +10:00

WuMing (无名) — AI PR Review for Forgejo

Licence: AGPL-3.0-or-later Status: Pre-release Python 3.12+

WuMing (无名, wúmíng) — Chinese for "nameless". A reviewer with no identity of its own: it speaks only through the code it examines.

Fetches a PR diff from the Forgejo/GitHub API, routes changed files to specialised AI agents, and posts inline review comments back to the PR. Works as a Woodpecker CI plugin (image: step) and as a native Forgejo/GitHub Actions action (uses: step). No Python to install in consumer repos.

Status

Available as a container image at registry.marvin8.zone/marvin8/wuming. Implements the Forgejo client, diff parser, multi-agent router (code, config, docs, shell, security), DeepSeek, Anthropic, and Ollama backends, comment deduplication, PR size gate, and OWASP Top 10 security review. Not yet production-hardened — use with caution and report issues on the issue tracker.

Verifying images

Images are signed with cosign v2 using a managed key; the public key lives in this repository as wuming.pub. Every image also carries a signed CycloneDX SBOM attestation.

With the cosign CLI

curl -O https://forge.marvin8.zone/marvin8/wuming/raw/branch/main/wuming.pub
cosign verify --key wuming.pub --insecure-ignore-tlog registry.marvin8.zone/marvin8/wuming:latest
cosign verify-attestation --key wuming.pub --insecure-ignore-tlog --type cyclonedx registry.marvin8.zone/marvin8/wuming:latest

With podman (pull-time enforcement)

Podman (via containers/image) verifies signatures at pull time, so podman run, quadlets, and CI runners using podman are all covered by two config files plus the public key. Rootless podman reads them from ~/.config/containers/, root podman (e.g. a runner using the docker-compatible socket) from /etc/containers/.

# containers/registries.d/cosign.yaml — enable reading cosign attachments
docker:
    registry.marvin8.zone:
        use-sigstore-attachments: true
// containers/policy.json — add under "transports" → "docker"
// (keep "default" permissive; scope the rule to this registry only)
"registry.marvin8.zone/marvin8/wuming": [
    {
        "type": "sigstoreSigned",
        "keyPath": "/etc/pki/containers/wuming.pub",
        "signedIdentity": { "type": "matchRepository" }
    }
]

matchRepository is required: cosign signatures only carry repository identity. Unsigned or wrongly-signed images are then refused at pull time.

Images are signed with cosign v2-format signatures (sha256-<digest>.sig tags). cosign v3 stores signatures as OCI referrers, which podman cannot yet verify.

Quick start

# .woodpecker/ai-review.yaml in your repo
when:
  event: pull_request

steps:
  - name: ai-review
    image: registry.marvin8.zone/marvin8/wuming:latest
    environment:
      WUMING_FORGEJO_TOKEN:
        from_secret: forgejo_token
      WUMING_DEEPSEEK_KEY:
        from_secret: deepseek_api_key
      WUMING_AGENTS: code,config

To use the Anthropic backend instead, swap the API key and set the backend:

      WUMING_ANTHROPIC_KEY:
        from_secret: anthropic_api_key
      WUMING_BACKEND: anthropic

To review with OpenRouter (one account, many providers), swap in the OpenRouter key and set the backend:

      WUMING_OPENROUTER_KEY:
        from_secret: openrouter_api_key
      WUMING_BACKEND: openrouter

Any other OpenAI-compatible endpoint (Groq, Together, vLLM, LM Studio, …) works via the generic openai backend — set WUMING_OPENAI_BASE_URL, WUMING_OPENAI_KEY, and WUMING_OPENAI_MODEL with WUMING_BACKEND: openai.

Forgejo/GitHub Actions

Forgejo Actions:

# .forgejo/workflows/ai-review.yml
on:
  pull_request:

jobs:
  ai-review:
    runs-on: zhuiri
    steps:
      - uses: https://forge.marvin8.zone/marvin8/wuming@main
        with:
          forgejo_token: ${{ secrets.WUMING_FORGEJO_TOKEN }}
          deepseek_key: ${{ secrets.WUMING_DEEPSEEK_KEY }}
          agents: code,config

runs-on: zhuiri is the self-hosted runner label on forge.marvin8.zone — swap it for your own runner's label on other Forgejo instances.

uses: https://forge.marvin8.zone/marvin8/wuming@<ref> builds the Containerfile from that ref on your runner — @main runs the latest commit, and pinning @v0.8.0 runs that release. Your runner needs a container builder (Docker or Podman) and access to pull the base images.

GitHub Actions (github.com): use uses: docker://registry.marvin8.zone/marvin8/wuming:latest instead of uses: https://forge.marvin8.zone/marvin8/wuming@main — WuMing is hosted on forge.marvin8.zone and has no GitHub mirror. Also replace the with: block with an env: block using WUMING_* variable names (e.g. WUMING_FORGEJO_TOKEN, WUMING_DEEPSEEK_KEY) — when GitHub Actions uses docker://, it does not process action.yml, so with: keys are not mapped to WUMING_* environment variables.

See the Forgejo/GitHub Actions guide for all inputs.

Configuration

Variable Default Description
WUMING_FORGEJO_TOKEN — Forgejo API token (required)
WUMING_FORGEJO_URL https://forge.marvin8.zone Forgejo instance base URL
WUMING_SETTLE_AUTHORS — Comma-separated logins trusted to settle findings without endpoint verification (e.g. the maintainer's agent account). Needed where the review token cannot read the collaborators list, such as Forgejo Actions. The repository owner is always authoritative. Note: granting this to the account that also generates findings means a manipulated run could suppress its own findings — grant deliberately
WUMING_BOT_LOGIN — Override the bot account's login used to recognise WuMing's own reviews and comments. Auto-detected from the API token (falling back to forgejo-actions); set it on deployments where the token has no backing user, such as Forgejo Actions
WUMING_DEEPSEEK_KEY — DeepSeek API key
WUMING_DEEPSEEK_MODEL — Override the default DeepSeek model (deepseek-v4-flash) for all agents without an explicit name:model; per-agent entries take precedence
WUMING_AGENTS code Comma-separated agent list; valid names: code, config, docs, performance, security, shell, tests; use name:model to set per-agent model (model names are backend-specific, e.g. code:deepseek-v4-flash,docs)
WUMING_MAX_TOKENS 2048 Max output tokens per backend call; auto-raised to 16384 for all OpenAI-compatible backends (deepseek, moonshot, openrouter, openai) since they may emit reasoning tokens
WUMING_SKIP_PATHS — Additional glob patterns to skip
WUMING_BACKEND deepseek deepseek | anthropic | ollama | moonshot | openrouter | openai
WUMING_OLLAMA_URL — Ollama base URL (required if backend=ollama)
WUMING_ANTHROPIC_KEY — Anthropic API key (required if backend=anthropic)
WUMING_MOONSHOT_KEY — Moonshot (Kimi) API key (required if backend=moonshot)
WUMING_MOONSHOT_MODEL — Override the default Moonshot model (kimi-k2.7-code) for all agents without an explicit name:model; per-agent entries take precedence
WUMING_OPENROUTER_KEY — OpenRouter API key (required if backend=openrouter)
WUMING_OPENROUTER_MODEL — Override the default OpenRouter model (deepseek/deepseek-v4.1-flash) for all agents without an explicit name:model; per-agent entries take precedence
WUMING_OPENAI_BASE_URL — Base URL of any OpenAI-compatible endpoint, e.g. https://llm.example/v1 (required if backend=openai)
WUMING_OPENAI_KEY — API key for the generic OpenAI-compatible endpoint; may be empty for keyless local servers (e.g. LM Studio), required for hosted endpoints
WUMING_OPENAI_MODEL — Default model for the generic OpenAI-compatible endpoint (required if backend=openai)
WUMING_PROGRESS — true/1 force on; false/0 force off; when unset or empty, auto-detects: enabled when stdout is a TTY and CI env var is absent
WUMING_MAX_DIFF_LINES 0 Maximum raw diff size in lines. When the diff exceeds this value and it is greater than 0, WuMing posts a single plain PR comment explaining the PR is too large to review automatically, then exits without posting inline comments. Set to 0 to disable.
WUMING_MAX_FILE_LINES 0 Maximum file size (in lines) for full-file context fetching. When greater than 0, WuMing fetches the complete content of each changed file from Forgejo and includes it in the agent's context, giving the model visibility beyond the diff hunks. Files exceeding this line count are excluded. Set to 0 (the default) to disable.
WUMING_MIN_SEVERITY (unset) Minimum severity for posted findings: low, medium, high, or critical. When a floor is set, findings below it are dropped before posting — including unrecognised severity values. Unset by default — all findings are posted. Only the four levels are accepted — any other value is an error at startup, not a fallback to posting everything.
WUMING_VERIFY true When true, each candidate finding is fact-checked against the changed file's full content before posting; findings whose factual claims the file contradicts are dropped. Verification is fail-open: provider errors keep findings. Set to false to disable. Only true/false (case-insensitive) are accepted — any other value is an error, not a fallback to the default.
WUMING_REVIEW_CONTEXT true When true, re-review waves receive the most recent WuMing review's findings (scoped to each agent's routed files) plus the conversation posted after it as prompt context, so answered or declined findings are not re-raised. The context block is capped and loading it is fail-open: if the conversation cannot be fetched, the review runs without it. Set to false for fully stateless reviews. Only true/false (case-insensitive) are accepted — any other value is an error.
WUMING_SKIP_UNCHANGED true When true, files that have not changed since the commit of the most recent WuMing review are skipped on re-reviews, so each wave focuses on what the fix actually touched. The comparison is fail-open: if it cannot be fetched, or no prior review exists, every file is reviewed. Set to false to re-review every changed file on every wave. Only true/false (case-insensitive) are accepted — any other value is an error.
WUMING_MAX_ROUNDS 0 Maximum number of WuMing review waves per pull request (counting every prior WuMing review). When the cap is reached, further waves are skipped and a single notice comment is posted instead of an inline review. 0 (the default) means unlimited. Only non-negative integers are accepted — non-integer or negative values are an error at startup.
WUMING_LEDGER true When true, maintainer decisions recorded with wuming: declined — <reason> or wuming: resolved with option N — <reason> replies are stored in a closed ledger issue and respected by future reviews on any pull request: exact repeats of a settled finding are dropped mechanically, and near-identical equivalents are suppressed via a settled-decisions prompt block. See "Settled decisions ledger" below. Fail-open: if the ledger cannot be fetched, reviews run without it. Only true/false (case-insensitive) are accepted — any other value is an error.
WUMING_LEDGER_ISSUE (unset) Pin the ledger issue number instead of auto-discovering it (by the wuming-ledger label, then the exact title WuMing: settled decisions). A pinned issue is written to even when WuMing did not create it — only pin an issue you designate as the ledger. Unset by default. Only positive integers are accepted — any other value is an error.
WUMING_DRY_RUN false When true, skips all Forgejo write calls (no comments posted) and logs the would-be comment bodies to stdout instead. All read operations still run.
WUMING_VERBOSE false When true, sets the wuming logger to DEBUG level. Each backend logs the full LLM request payload (including diff text and file contents) and raw response before parsing. Treat these logs as sensitive — they may contain repository source code.
WUMING_SUMMARY_COMMENT false When true, posts a plain PR comment after the review with a per-agent severity count table. Posted even when no new inline comments are found. Skipped when the diff-too-large early exit fires.

Finding verification

Before any finding is posted, WuMing fact-checks it: a dedicated LLM call receives the finding plus the full content of the changed file and decides whether the file actually contradicts the finding's factual claims. Only findings the file demonstrably contradicts are dropped — the verifier never judges style, importance, or severity, and it only sees the changed file itself, so claims about other files ("no test exists") are not verified.

Verification is fail-open: a provider error or unparseable verdict keeps the finding, and a crash of the verification pass itself posts the findings unverified. Files whose content cannot be fetched, or that exceed 2000 lines, skip verification entirely — this 2000-line cap is a fixed internal limit, independent of WUMING_MAX_FILE_LINES, which only controls how much context the review agents see. The pass adds one LLM call per finding (at most 4 run concurrently), after the cheap filters — severity floor, line-in-diff, deduplication — so LLM spend goes only to findings that would otherwise be posted. Set WUMING_VERIFY=false to disable.

Settled decisions ledger

When you decline a finding (or pick one of its options), the same class of finding tends to come back on the next pull request that touches the same code. The ledger ends that: settle a question once, and every future review respects it.

To settle a finding, reply on the pull request with a marker line:

wuming: declined — debug logging is intentional and documented in the README
wuming: resolved with option 2 — go with the router-based approach

The marker line must lead your reply. You can reply threaded to the finding, or as a plain comment — plain replies are harvested when they are unambiguous (the PR has exactly one open finding, you name the path: wuming: declined docs/api.md — reason, or you quote the finding's hash prefix — the hex in the wuming:sha256 marker on the finding's comment, at least 7 characters: wuming: declined 105f73a — reason). Anything ambiguous is skipped and logged, never guessed. Only the repository owner and users with write access can settle findings.

WuMing stores each decision as a comment on a closed issue titled WuMing: settled decisions (label wuming-ledger), which it creates on first use — the issue stays closed and never counts as open work. WuMing only ever writes into that issue; a human-created issue carrying the label is left alone.

Future reviews suppress settled findings twice over: an exact repeat is dropped mechanically (same sha256 marker), and near-identical equivalents are suppressed through a settled-decisions block in the agent prompt — agents may raise one again only if a changed hunk makes the settled decision genuinely unsafe, and must say why. On every run WuMing also sweeps recent pull requests (all open PRs plus PRs merged within 60 days, most recent 25) so a decline posted after a PR's final review wave still reaches the ledger. Everything is fail-open — if the ledger cannot be reached, reviews run without it — and WUMING_DRY_RUN=true never writes to it. Set WUMING_LEDGER=false to disable.

Review policy file

A repository can declare its review ground up front, without waiting for a finding to be raised first: a committed .wuming.yml at the repo root, read from the repository's default branch — never from the pull request under review, so a PR author cannot shape their own review's context.

context: >
  This project prefers explicit, readable code over abstraction;
  debug logging in scripts is a documented feature.

rules:
  - paths: [".forgejo/workflows/*.yml"]
    note: >
      Action pinning to release tags is a deliberate trade-off here;
      don't raise it.

context reaches every agent; each rule reaches only the agents whose routed files match its paths globs. Declared ground is soft context, never mechanical suppression: agents are asked not to re-raise it unless a changed hunk genuinely makes the decision unsafe, and to say why if they do. Fail-open everywhere: no file means today's behaviour, a malformed file logs a warning and the review proceeds without it. See the review policy reference for the full shape and its relation to the settled-decisions ledger.

Agents

Agent Files Focus
code *.py, *.go, *.ts, … Correctness, logic bugs
config *.toml, *.yaml, *.json Schema, secret hygiene
docs *.md, *.rst Clarity, accuracy
performance *.py, *.go, *.ts, *.sql, … N+1 queries, O(n²) loops, I/O in loops, missing indexes
security code + config + shell files OWASP Top 10 security vulnerabilities
shell *.sh, Dockerfile, CI files Shell safety, image hygiene
tests *.py, *.go, *.ts, … Assertion quality, global state teardown, coverage gaps

Handling large PRs

WuMing has two mechanisms to stay within token and API limits when a PR is unusually large.

Size gate (WUMING_MAX_DIFF_LINES): if the total raw diff line count exceeds this value, WuMing posts a single plain PR comment explaining that the PR is too large to review automatically, then exits without posting any inline comments. Set to 0 (the default) to disable the gate entirely.

Hunk size cap: individual diff hunks longer than 300 lines are replaced with a single stub line showing the line count, e.g. [... 450 lines truncated — too large for review ...]. The hunk header (filename and position) is preserved so the agent still knows which file and region was affected.

Woodpecker CI variables injected automatically

Variable Description
CI_REPO_OWNER Repository owner
CI_REPO_NAME Repository name
CI_COMMIT_PULL_REQUEST PR number (absent on non-PR events)
CI_COMMIT_SHA Head commit SHA

About

This project was developed with the assistance of Claude Code. All code has been reviewed by a human before merging. WuMing also reviews its own pull requests — a small demonstration of the workflow it enables.