wehub-resource-sync
a06f331eb8
CI / benchmark (push) Has been skipped
install-script / posix-syntax (push) Successful in 6m1s
CI / build-onnx (push) Failing after 6m43s
init-smoke / dry-run (push) Failing after 15m57s
security / govulncheck (push) Has been cancelled
security / trivy-fs (push) Has been cancelled
CI / test (1.26, ubuntu-latest) (push) Has been cancelled
Scorecard supply-chain security / Scorecard analysis (push) Has been cancelled
CI / test (1.26, macos-latest) (push) Has been cancelled
CI / build-windows (push) Has been cancelled
CI / lint (push) Has been cancelled
install-script / powershell-syntax (push) Has been cancelled
install-script / install (macos-14) (push) Has been cancelled
install-script / install (ubuntu-latest) (push) Has been cancelled
111 lines
4.6 KiB
Markdown
111 lines
4.6 KiB
Markdown
# Pull-request actions
|
|
|
|
The daemon exposes a small set of data-only MCP tools over your repository's
|
|
pull requests:
|
|
|
|
- **`list_prs`** — list a repo's PRs with a one-shot review-state
|
|
classification (DRAFT / BASE_MISMATCH / CHANGES_REQUESTED / APPROVED /
|
|
STALE / READY), a normalized CI rollup, and per-PR merge blockers.
|
|
- **`get_pr_impact`** — map a PR's changed files to the symbols they define,
|
|
score PR-level risk across five axes, and group the affected surface by
|
|
community and by caller/test file. Set `receipt: true` for a small,
|
|
privacy-safe review receipt.
|
|
- **`triage_prs`** — rank a repo's open PRs by graph-derived review priority
|
|
(highest risk first, deterministic).
|
|
|
|
These tools are **read-only** — none of them edits code or posts to GitHub.
|
|
|
|
## Providing a GitHub token to the daemon
|
|
|
|
The daemon **self-serves** PR data: it pairs a GitHub token with the repo
|
|
identity it already indexed, so there is no CLI-versus-daemon auth split and
|
|
no dependency on a `gh` CLI login. All it needs is a token in **the daemon's
|
|
own environment**.
|
|
|
|
The token resolves from, in order:
|
|
|
|
1. `GH_TOKEN`
|
|
2. `GITHUB_TOKEN`
|
|
|
|
Set one of these in the environment the daemon process runs under — not in
|
|
your interactive shell, unless the daemon inherits it. For example, when
|
|
starting the daemon manually:
|
|
|
|
```bash
|
|
GH_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx gortex daemon start --detach
|
|
```
|
|
|
|
For a long-running daemon managed by a service supervisor, set the variable in
|
|
that unit's environment (e.g. a systemd `Environment=` line, a launchd
|
|
`EnvironmentVariables` entry, or your process manager's env file) so it is
|
|
present every time the daemon starts.
|
|
|
|
GitHub Enterprise: when `GITHUB_API_URL` or `GH_HOST` names a non-`github.com`
|
|
host, the forge client targets that Enterprise API base automatically. The
|
|
same `GH_TOKEN` / `GITHUB_TOKEN` resolution applies.
|
|
|
|
In CI, a per-PR Action's `GITHUB_TOKEN` is picked up automatically — no extra
|
|
configuration is needed.
|
|
|
|
## When no token is available
|
|
|
|
If no token is resolvable **and** you did not supply already-fetched data,
|
|
each tool degrades gracefully instead of failing:
|
|
|
|
```json
|
|
{ "error": "forge unavailable",
|
|
"hint": "set GH_TOKEN (or GITHUB_TOKEN) in the daemon environment" }
|
|
```
|
|
|
|
A GitHub rate-limit is surfaced as a typed degradation carrying the
|
|
Retry-After hint:
|
|
|
|
```json
|
|
{ "error": "rate limited", "retry_after_s": 42 }
|
|
```
|
|
|
|
## Skipping the network with caller-supplied data
|
|
|
|
Every tool accepts an optional caller-supplied data path so an agent (or a CLI
|
|
front-end) that already fetched the PR data can avoid a refetch:
|
|
|
|
- `list_prs` accepts `prs` — a JSON array of already-fetched PR objects.
|
|
- `get_pr_impact` accepts `files` — a JSON array of changed file paths.
|
|
- `triage_prs` accepts `prs` and/or `files` (a JSON object mapping a PR
|
|
number to its changed file paths).
|
|
|
|
When supplied data is present, the tool classifies / scores it directly and
|
|
makes no network call. Triage additionally caches each fetched PR for a short
|
|
window so a re-run within the window does not refetch the same PR.
|
|
|
|
## Per-PR reviewer graph bundle
|
|
|
|
`gortex prs bundle <number>` writes a self-contained, reviewer-focused slice of
|
|
the knowledge graph to a JSON file (`--out`, default `pr-<number>-bundle.json`):
|
|
|
|
- the PR's **changed files**,
|
|
- the graph-joined **impact** — the blast radius, the five-axis PR-risk score,
|
|
and a small privacy-safe **review receipt** (risk tier + next-safe-action +
|
|
merge-blocker verdict) — taken verbatim from `get_pr_impact`,
|
|
- the ranked **reviewer suggestions** from `suggest_reviewers` (CODEOWNERS +
|
|
recent authorship + co-change experts).
|
|
|
|
The bundle is deterministic for an unchanged PR (the changed-file list is
|
|
sorted and the JSON is stably indented), so it can be uploaded as a CI artifact
|
|
and diffed across runs. The command is daemon-first: the forge supplies the
|
|
changed-file set and the daemon joins it against the indexed graph — no second
|
|
in-process index. A failing `suggest_reviewers` (missing token / CODEOWNERS)
|
|
does not sink the bundle; the reviewers section is simply omitted.
|
|
|
|
### Wiring it into CI
|
|
|
|
A ready-to-use GitHub Action template lives at
|
|
[`.github/workflows/gortex-pr-review.yml.example`](../../.github/workflows/gortex-pr-review.yml.example).
|
|
The `.yml.example` suffix means GitHub does **not** run it as-is — copy it to
|
|
`.github/workflows/gortex-pr-review.yml` in your repository to enable it. On
|
|
each `pull_request` it builds gortex, starts the daemon, indexes the checked-out
|
|
repo, runs `gortex prs bundle <N>`, and uploads the bundle with
|
|
`actions/upload-artifact`. It maps the Action-provided `GITHUB_TOKEN` to
|
|
`GH_TOKEN` so the daemon self-serves the PR's changed files with no extra secret
|
|
configuration.
|