MR Principles Review Agent

Open-source reviewer for GitLab merge requests and GitHub pull requests. It checks changed code against your engineering principles and posts concise findings back to the review thread.

Features

• VCS support: GitLab + GitHub
• Repo/principles agnostic via environment variables
• OpenAI structured review output
• Findings-only note with copyable Agent prompt
• Diff-hash dedupe to avoid repeat spend
• Cost/scope guardrails

Installation

Run directly with npx:

npx --yes @pulkit004/mr-principle-review-agent

Or install in your project:

npm install --save-dev @pulkit004/mr-principle-review-agent

Then run:

npx mr-principles-review

Quick Start

1. Provide required environment variables for your provider and OpenAI.
2. Provide principles via MR_REVIEW_PRINCIPLES_TEXT or MR_REVIEW_PRINCIPLES_FILE.
3. Run:

npx --yes @pulkit004/mr-principle-review-agent

For local development in this repository:

npm ci
npm start

Provider Selection

• Explicit: MR_REVIEW_VCS_PROVIDER=gitlab or github
• Auto-detect:
  • GitHub when GITHUB_REPOSITORY or GITHUB_ACTIONS exists
  • otherwise GitLab

Required Environment Variables

Common:

• OPENAI_API_KEY
• MR_REVIEW_PRINCIPLES_TEXT or MR_REVIEW_PRINCIPLES_FILE

GitLab mode:

• GITLAB_TOKEN (or CI_JOB_TOKEN)
• CI_API_V4_URL
• CI_PROJECT_ID
• CI_MERGE_REQUEST_IID

GitHub mode:

• GITHUB_TOKEN (or GH_TOKEN)
• GITHUB_REPOSITORY (owner/repo)
• PR number from one of:
  • GITHUB_PR_NUMBER
  • GITHUB_REF (refs/pull/<id>/merge)
  • GITHUB_EVENT_PATH

Optional Environment Variables

• OPENAI_MODEL (default: gpt-4.1-mini)
• MR_REVIEW_VCS_PROVIDER (gitlab|github)
• MR_REVIEW_CODE_FILE_REGEX (default: \\.(ts|tsx|js|jsx)$)
• MR_REVIEW_TARGET_BRANCHES (default: main)
• MR_REVIEW_MAX_DIFF_CHARS (default: 60000)
• MR_REVIEW_MAX_OUTPUT_TOKENS (default: 700)
• MR_REVIEW_MAX_FINDINGS (default: 3)
• MR_REVIEW_MIN_SEVERITY (default: low)
• MR_REVIEW_FORCE_REVIEW (true/false)
• MR_REVIEW_BLOCKING (true/false)
• MR_REVIEW_GUARDRAIL_ENFORCE (default: true)
• MR_REVIEW_MAX_ESTIMATED_RUN_COST_USD (default: 0.20)
• MR_REVIEW_ESTIMATED_OUTPUT_TOKENS (default: 900, used for pre-run cost estimate)
• MR_REVIEW_MONTHLY_MR_COUNT (default: 120)
• MR_REVIEW_MONTHLY_BUDGET_USD (default: 30)
• MR_REVIEW_PRICE_GPT41_MINI_INPUT_PER_1M (default: 0.40)
• MR_REVIEW_PRICE_GPT41_MINI_OUTPUT_PER_1M (default: 1.60)
• MR_REVIEW_PRICE_GPT41_INPUT_PER_1M (default: 2.00)
• MR_REVIEW_PRICE_GPT41_OUTPUT_PER_1M (default: 8.00)

CI Templates

• GitLab: templates/gitlab-ci.yml
• GitHub Actions: templates/github-pr-review.yml

Output

The posted comment contains:

• Severity + principle
• File
• Issue
• Agent prompt in a copyable fenced block

Security Reporting

See SECURITY.md for private vulnerability reporting.

Contributing

See CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SUPPORT.md.

Release Process

• CI runs on pushes and pull requests across Node 20 and 22.
• Releases are tag-driven (vX.Y.Z) through GitHub Actions.
• Publish requires NPM_TOKEN in repository secrets.

Test

npm test