Review Relay

A CLI tool that syncs GitLab merge request and GitHub pull 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 code review discussions and your local filesystem with two commands:

1. read — fetches unresolved discussions from a GitLab MR or GitHub PR and writes them to feedback.md
2. write — parses responses from feedback.md and submits them back as discussion replies

GitLab and GitHub both support read and write.

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 review 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 the provider.

The agent is instructed to replace each TODO with either 👍 (feedback accepted and applied, optionally followed by a brief clarification if it provides useful context or flags a concern) or a detailed technical explanation if it disagrees. Discussions marked (non-resolvable) are optional to react to, so the agent can leave TODO unchanged when no reply is needed.

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
# or
GITLAB_TOKEN=your-token-here

# For GitHub support:
REVIEW_RELAY_GITHUB_TOKEN=your-token-here
# or
GITHUB_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

Provider selection

Review Relay chooses the provider in this order:

1. REVIEW_RELAY_PROVIDER, when set to gitlab or github.
2. Provider-specific token or override variables, when only one provider family is configured.
3. remote.origin.url host: github.com selects GitHub, and gitlab.com or gitlab.* selects GitLab. This is also used when both GitHub and GitLab variables are present.

Set REVIEW_RELAY_PROVIDER when auto-detection is ambiguous.

GitLab

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 |

GitHub

Required for GitHub:

| Variable | Description | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | REVIEW_RELAY_GITHUB_TOKEN or GITHUB_TOKEN | GitHub token with pull request read/write permission. The relay-specific variable takes precedence. | | REVIEW_RELAY_PROVIDER=github | Optional when the remote is on github.com or another GitHub variable is set; useful for ambiguous remotes. |

Optional:

| Variable | Default | Description | | ----------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------- | | REVIEW_RELAY_GITHUB_REPOSITORY | Inferred from git remote | Repository path in owner/repo format. | | REVIEW_RELAY_GITHUB_PULL_REQUEST_NUMBER | Auto-detected by branch | Override which PR to use by number. Required for fork PRs or ambiguous branch matching. | | REVIEW_RELAY_GITHUB_API_BASE_URL | Inferred/defaulted | REST API base URL. Defaults to https://api.github.com for github.com remotes. | | REVIEW_RELAY_GITHUB_GRAPHQL_URL | Octokit default | Optional exact GraphQL endpoint URL. Useful for GitHub Enterprise when the REST base is wrong. |

Read options

| Option | Description | | ----------------------------- | ----------------------------------------------------------------- | | --include-current-user | Include discussions where the latest note is by the current user. | | --output <file> | 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. | | --skip-instructions | Omit generated instructions from the feedback markdown. | | --extra-instructions <text> | 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 MR notes or PR conversation comments. |

Auto-detection

By default, the provider and project path are read from git remote.origin.url. Supported formats:

• [email protected]:group/project.git
• ssh://[email protected]/group/project.git
• https://gitlab.com/group/project.git
• [email protected]:owner/repo.git
• ssh://[email protected]/owner/repo.git
• https://github.com/owner/repo.git

The current git branch is used to find the matching open MR or PR. Set REVIEW_RELAY_GITLAB_MERGE_REQUEST_IID or REVIEW_RELAY_GITHUB_PULL_REQUEST_NUMBER to override if multiple reviews exist for the same branch. GitHub fork PRs usually need REVIEW_RELAY_GITHUB_PULL_REQUEST_NUMBER.

Discussion filtering

The read command includes discussions that need attention or may deserve a response:

• Resolved discussions are excluded unless --include-resolved is set.
• System notes (auto-generated by GitLab) are excluded.
• GitHub PR review summaries are included by default and marked as non-resolvable.
• Standalone MR notes or PR conversation comments 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. GitHub review threads that are outdated but still unresolved are marked with (outdated). Discussions without resolvable notes are marked with (non-resolvable); reacting to them is optional, but still possible when a useful reply is needed.

For GitHub, threaded review discussions are submitted as pull request review comment replies. Responses to PR review summaries and standalone PR conversation comments are submitted as new PR conversation comments with a short reference to the original item.

Commands

review-relay read [options] Fetch unresolved review discussions
review-relay write          Submit responses from feedback.md
review-relay --help         Show help
review-relay --version      Show version