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:

npm install --save-dev review-relay

Then run via npx or add scripts to package.json:

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 to load them from a .env file:

# .env
REVIEW_RELAY_GITLAB_PRIVATE_TOKEN=your-token-here

npx dotenv review-relay read
npx dotenv review-relay write

Or add convenience scripts to package.json:

{
  "scripts": {
    "review:read": "dotenv review-relay read",
    "review:write": "dotenv review-relay write"
  }
}

Environment variables

Required

Variable	Description
REVIEW_RELAY_GITLAB_PRIVATE_TOKEN	GitLab access token with api scope

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

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.
• System notes (auto-generated by GitLab) are excluded.
• Discussions where you already replied last are excluded.

Commands

review-relay read       Fetch unresolved merge request discussions into feedback.md
review-relay write      Submit responses from feedback.md to merge request discussions
review-relay --help     Show help
review-relay --version  Show version