https://github.com/xfiveco/review-relay
https://github.com/xfiveco/review-relay
Last synced: 23 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/xfiveco/review-relay
- Owner: xfiveco
- Created: 2026-02-27T07:06:17.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-05-28T00:24:44.000Z (about 1 month ago)
- Last Synced: 2026-05-28T02:19:56.380Z (about 1 month ago)
- Language: TypeScript
- Size: 113 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Review Relay
A CLI tool that syncs GitLab merge request discussions with a local `feedback.md` file, designed for AI-assisted code review workflows.
## AI-assisted project setup
Paste the following into an AI coding agent to set up review-relay in your project:
```
Set up review-relay in this project:
1. Detect the package manager from lock files and install review-relay as a
dev dependency.
2. Read node_modules/review-relay/README.md, then interactively walk the user
through auth and configuration in the context of this project — ask
questions, confirm choices, and explain decisions as you go.
3. Add review:read and review:write scripts to package.json based on the
chosen auth approach.
4. Add a brief section to the project README or other relevant documentation
describing the review:read and review:write scripts and their agentic
workflow — omit one-time setup details.
5. Offer to add /feedback.md to .gitignore — it's a generated per-session file
that shouldn't be committed.
```
## How It Works
Review Relay bridges GitLab MR discussions and your local filesystem with two commands:
1. **`read`** — fetches unresolved discussions from a GitLab MR and writes them to `feedback.md`
2. **`write`** — parses responses from `feedback.md` and submits them back to GitLab as discussion replies
### AI-assisted review workflow
The generated `feedback.md` includes instructions tailored for an AI coding agent. The intended flow is:
1. Run `npx review-relay read` to export unresolved MR discussions to `feedback.md`.
2. Hand `feedback.md` to your AI agent — it reads the discussions, analyzes the referenced files, makes necessary code changes, and fills in the responses.
3. Run `npx review-relay write` to submit the responses back to GitLab.
The agent is instructed to replace each `TODO` with either `👍` (feedback accepted and applied) or a detailed technical explanation if it disagrees.
## Installation
Requires Node.js >= 20. Install locally in your project:
```bash
npm install --save-dev review-relay
```
Then run via `npx` or add scripts to `package.json`:
```bash
npx review-relay read
npx review-relay write
```
## Configuration
Review Relay is configured via environment variables. You can export them in your shell or use a tool like [`dotenv-cli`](https://github.com/entropitor/dotenv-cli) to load them from a `.env` file:
```bash
# .env
REVIEW_RELAY_GITLAB_PRIVATE_TOKEN=your-token-here
# or
GITLAB_TOKEN=your-token-here
```
```bash
npx dotenv review-relay read
npx dotenv review-relay write
```
Or add convenience scripts to `package.json`:
```json
{
"scripts": {
"review:read": "dotenv review-relay read",
"review:write": "dotenv review-relay write"
}
}
```
### Environment variables
#### Required
| Variable | Description |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `REVIEW_RELAY_GITLAB_PRIVATE_TOKEN` or `GITLAB_TOKEN` | GitLab access token with `api` scope. The relay-specific variable takes precedence. |
A **project access token** is recommended over a personal access token — it scopes permissions to a single project. Create one under **Settings → Access Tokens** in your GitLab project. The token needs at least the **Reporter** role to read discussions and post notes.
#### Optional
| Variable | Default | Description |
| --------------------------------------- | ------------------------ | ------------------------------------------------------- |
| `REVIEW_RELAY_GITLAB_HOST` | Inferred from git remote | GitLab instance URL (e.g. `https://gitlab.example.com`) |
| `REVIEW_RELAY_GITLAB_PROJECT_PATH` | Inferred from git remote | Project path (e.g. `group/subgroup/project`) |
| `REVIEW_RELAY_GITLAB_MERGE_REQUEST_IID` | Auto-detected by branch | Override which MR to use by IID |
### Read options
| Option | Description |
| ----------------------------- | ------------------------------------------------------------------------ |
| `--include-current-user` | Include discussions where the latest note is by the current GitLab user. |
| `--output ` | Write feedback to a file path. Defaults to `feedback.md`. |
| `--stdout` | Print feedback markdown to stdout instead of writing a file. |
| `--agent` | Print feedback as an agent prompt; replies should be MR notes. |
| `--skip-instructions` | Omit generated instructions from the feedback markdown. |
| `--extra-instructions ` | Append extra instructions to the feedback markdown. |
| `--include-context` | Include review context such as branches and description. |
| `--include-resolved` | Include resolved discussions. |
| `--include-standalone-notes` | Include standalone merge request notes. |
#### Auto-detection
By default, the GitLab host and project path are read from `git remote.origin.url`. Supported formats:
- `git@gitlab.com:group/project.git`
- `ssh://git@gitlab.com/group/project.git`
- `https://gitlab.com/group/project.git`
The current git branch is used to find the matching open MR. Set `REVIEW_RELAY_GITLAB_MERGE_REQUEST_IID` to override if multiple open MRs exist for the same branch.
## Discussion filtering
The `read` command only includes discussions that need attention:
- **Resolved discussions** are excluded unless `--include-resolved` is set.
- **System notes** (auto-generated by GitLab) are excluded.
- **Standalone MR notes** are excluded unless `--include-standalone-notes` is set.
- **Discussions where you already replied last** are excluded unless `--include-current-user` is set.
Resolved discussions included with `--include-resolved` are marked with `(resolved)` in the
discussion heading.
## Commands
```
review-relay read [options] Fetch unresolved merge request discussions
review-relay write Submit responses from feedback.md
review-relay --help Show help
review-relay --version Show version
```