Reviews GitHub pull requests for the Medusa repository. Checks PR template compliance, contribution guidelines, code conventions, and community contribution limits. Posts a review comment and applies initial-approval or requires-more label. Use when a PR is opened or updated.
Reviews GitHub pull requests for Medusa. Checks template compliance, contribution guidelines, code conventions, and community limits. Posts a concise review comment and applies a label.
⚠️ The quick reference in this file is NOT sufficient on its own. You MUST load the relevant reference files before executing each step.
Load these references based on what you're doing:
reference/contribution-types.md firstreference/conventions.md firstreference/comment-guidelines.md first (includes bug, security, and performance reporting formats)Minimum requirement: Load at least the relevant reference file(s) before completing the review.
| Argument | Required | Description |
|---|---|---|
pr_number | Yes | GitHub PR number to review |
title | No | PR title (fetched via script if omitted) |
author | No | PR author login (fetched via script if omitted) |
If title or author are not provided, fetch them with:
bash scripts/get_pr.sh <pr_number>
bash scripts/get_pr.sh <pr_number> # Fetch PR details (title, body, author, diff stats)
bash scripts/get_pr_files.sh <pr_number> # List files changed in the PR as JSON (metadata only)
bash scripts/get_pr_diff.sh <pr_number> # Fetch the full unified diff of the PR (required for code review)
bash scripts/get_linked_issues.sh <pr_number> # Fetch issues linked with closing keywords
bash scripts/get_comments.sh <pr_number> # Fetch all existing comments on the PR
bash scripts/get_labels.sh <pr_number> # Fetch current labels on the PR
bash scripts/add_comment.sh <pr_number> <body> # Post a comment on the PR
bash scripts/labels.sh <pr_number> <action> <label> # Manage labels: action is "add" or "remove"
bash scripts/close_issue.sh <pr_number> # Close the PR
bash scripts/get_issue.sh <issue_number> # Fetch a linked issue's details
If title/author were not passed as arguments:
bash scripts/get_pr.sh <pr_number>
Always fetch current labels, changed files, the full diff, and prior comments:
bash scripts/get_labels.sh <pr_number>
bash scripts/get_pr_files.sh <pr_number>
bash scripts/get_pr_diff.sh <pr_number>
bash scripts/get_comments.sh <pr_number>
Read the existing comments fetched in Step 1. Identify any previous bot review comments (comments from this automation) that raised issues or made requests.
For each previously raised issue or remark, determine whether it has been addressed in the current state of the PR:
CRITICAL: Do not repeat the full explanation for issues already raised in a previous comment. Keep follow-up reviews concise — assume the contributor has read the prior feedback.
Read .github/teams.yml. If the PR author's login appears in the list, they are a team member — skip steps 3 and 4 entirely and proceed directly to step 5.
The PR body must follow .github/pull_request_template.md. It requires these sections to be filled in (not left as placeholder text):
If any section is missing or contains only the placeholder ("Please provide answer here"), post a comment requesting it be filled out, apply requires-more, and stop.
Comment template — incomplete template:
Thank you for your contribution, @<author>!
Could you please fill in the PR description following our [pull request template](https://github.com/medusajs/medusa/blob/develop/.github/pull_request_template.md)? We need the **What**, **Why**, **How**, and **Testing** sections completed so we can review your PR efficiently.
Once you've updated the description, another review will be triggered automatically.
Thanks!
4a. Massive changes:
If the PR has more than 500 changed lines (additions + deletions) or more than 20 changed files:
bash scripts/get_linked_issues.sh <pr_number>
Check whether any linked issue carries a help-wanted label. If not, apply requires-more and comment explaining that large contributions should be scoped and pre-approved via an issue first (reference CONTRIBUTING.md).
bash scripts/get_linked_issues.sh <pr_number>
Look for closing keywords (closes, fixes, resolves + #<number>) in the PR body. Note whether a verified, open issue is linked.
Inspect the changed file paths and load the relevant reference section:
| Paths changed | Contribution type |
|---|---|
www/apps/ or www/packages/docs-ui/ | Docs → load reference/contribution-types.md Docs section |
packages/admin/dashboard/src/i18n/translations/ | Admin translation → load reference/contribution-types.md Admin Translations section |
packages/, integration-tests/, or other | Code → load reference/contribution-types.md Code section |
For mixed PRs, apply all relevant types.
Load reference/conventions.md and verify the changed files follow Medusa's conventions. Focus on the areas most relevant to the contribution type (e.g., API conventions for code changes, MDX structure for docs changes).
CRITICAL — Read full file context: For every file you intend to flag an issue in, read the entire file (not just the diff lines) before raising a concern. A pattern that looks wrong in isolation may be handled correctly later in the file, overridden by a wrapper, or follow an established project convention. Only flag an issue after confirming it is not resolved elsewhere in the file.
CRITICAL — Only flag new code: The diff contains both removed lines (prefixed
-) and added lines (prefixed+). Only raise issues about added/new lines. Never request changes to lines that were already modified as part of this PR — the new version of those lines is what matters, not the old one.
CRITICAL: This step applies to all PRs, including team members. Read the actual diff — do not rely only on file path inspection. Before flagging any issue, read the full file to confirm the concern is not already handled elsewhere. Only flag issues present in the new (added) lines of the diff, not in lines that were removed or already changed by this PR.
Check for the following security issues:
Authentication & Authorization:
Injection & Execution:
eval(), new Function(), or vm.runInContext() with untrusted datarequire()/import() with user-controlled pathsexec, spawn, execSync)Input Validation:
fs.readFile, path.join) without sanitization → path traversalData Exposure:
Dependencies & Supply Chain:
package.json — verify they're well-known, not typosquats, and have a clear purposescripts entries in package.json (e.g., postinstall, preinstall) that execute commandspackage.json changesMalicious code: If clearly malicious code is found → close the PR immediately:
bash scripts/close_issue.sh <pr_number>
For each confirmed or suspected security issue:
Security issues are always blocking — apply requires-more even if everything else looks good. Load reference/comment-guidelines.md for the Security Issues comment format.
CRITICAL: This step applies to all PRs. Only flag issues that would plausibly cause measurable degradation in production — not theoretical micro-optimizations. Before flagging, read the full file to confirm the issue is not already handled elsewhere. Only flag issues in the new (added) lines of the diff.
Check for:
Database / Query Performance:
query.graph(), query.index(), or service call inside a loop over a result set. Flag the loop location and the repeated call.query.graph() / remoteQueryObjectFromString() / service list calls missing pagination: req.queryConfig.pagination. A missing pagination object means a full-table scan.count, offset (metadata.skip), and limit (metadata.take) from the response body, breaking client-side pagination.filters or order in a query call without a corresponding index in the entity decorator or migration.Async & Concurrency:
await in a loop where Promise.all() would workMemory & Payload:
For each performance issue found:
Performance issues severity:
CRITICAL: This step applies to all PRs including team members. Any potential bug — confirmed or suspected — is a required change and must result in
requires-more. Do not leave bugs as notes.
CRITICAL — Read full file before flagging: For every file where you intend to flag a bug, read the entire file first. A bug in the diff may be handled by a guard, a wrapper, or a caller further in the file. Only flag a bug after confirming it is not already handled in the full file context.
CRITICAL — Only flag new code: Only raise bugs against lines that were added in this PR (diff lines prefixed
+). Do not flag lines that were removed (-) or lines that are unchanged context. Do not request changes to code that was already changed by this PR.
Read the actual code diff carefully. Flag anything that would plausibly cause incorrect runtime behaviour. Focus on:
await, unhandled promise rejections, race conditionscreateStep with side effects but no compensation function, meaning failed workflows leave orphaned dataFor each potential bug found:
Do NOT flag style issues, code smell, or naming preferences here. Only flag things that would plausibly cause incorrect behaviour at runtime. If you're uncertain, phrase it as a question but still add it to Required changes — it is the author's responsibility to confirm or disprove it.
Before writing the review, assess whether the changes make sense in the broader context of the PR. Load reference/comment-guidelines.md (Contextual Assessment section) for the full checklist. Key questions:
Note any concerns to include in the review comment.
Load reference/comment-guidelines.md for comment templates and tone guidance.
Decide the outcome:
| Label | When |
|---|---|
initial-approval | PR follows all guidelines, no security/performance blockers; team will do the final review |
requires-more | PR needs changes — list exactly what must change |
CRITICAL: Any security issue, any potential bug, or any blocking performance issue (N+1, unbounded query) must result in
requires-more, even if all other checks pass. Do not applyinitial-approvalwith bugs or security issues as notes — they are always required changes.
Post the comment, apply the label, and remove the opposite label:
bash scripts/add_comment.sh <pr_number> "<body>"
bash scripts/labels.sh <pr_number> add initial-approval
bash scripts/labels.sh <pr_number> remove requires-more
or
bash scripts/add_comment.sh <pr_number> "<body>"
bash scripts/labels.sh <pr_number> add requires-more
bash scripts/labels.sh <pr_number> remove initial-approval
CRITICAL: A PR must never have both
initial-approvalandrequires-moreat the same time. Whenever you add one, always remove the other — even if the other label wasn't set by you.
www/packages/docs-ui/ changespackages/medusa/src/api/initial-approval when a confirmed security or blocking performance issue was found-) or unchanged context lines — only flag issues in the new added (+) lines of the diff@mention the authorinitial-approval and requires-more on a PR — always remove the opposite label when adding onereference/conventions.md - Medusa coding conventions to verify
reference/contribution-types.md - How to verify code, docs, and admin translation contributions
reference/comment-guidelines.md - Comment writing rules and templates