GitHub App for AI pull request review: install, permissions and what it posts

MergeJudge is an AI pull request reviewer with an open-source engine. Install the GitHub App, pick the repositories, and sign in to the panel. Public repos get free AI reviews to start, with no key; for private repos or more volume, add your own model key or connect a runner. Every pull request gets a lane, a summary comment, line comments on findings and a mergejudge/lane check.

The lanes are auto (low risk, can go straight through; that is not a guarantee, and branch protection and required checks still apply), review (a human must look) and block (do not merge). MergeJudge doesn't merge pull requests itself.

The hosted App is not open source. The runner repository, the npm package and the GitHub Action are the open-source AI pull request reviewer.

GitHub App, GitHub Action or runner: which one?

	GitHub App (hosted)	GitHub Action	Runner
Install	Install the App, then sign in to the panel	One workflow file	npx mergejudge-runner setup, with the App already installed
MergeJudge account	Yes. You sign in to the panel	No	Yes. The App is installed, and you administer that installation
Where the AI step runs	On the hosted service, which calls your provider with your key	In your GitHub Actions runner, which calls your provider	On your machine, with your Claude Code or Codex login, or a GLM key
Review modes	diff and context. Deep mode with a hosted code index is not offered	diff, context and deep (deep needs an actions/checkout step)	diff, context and deep

The hosted service guide is the reference for the App. The Action does not call that service and does not need a MergeJudge account. The runner connects to the hosted service and runs the AI step on your machine. If a repo also has the MergeJudge Action workflow, remove it, or both will post.

Install the GitHub App

1. Install the MergeJudge GitHub App on your user account or organization. The App page is github.com/apps/mergejudge.
2. Pick the repositories it should review.
3. Open the manager panel and sign in with GitHub. You see only installations you administer.
4. Open a pull request. Public repos get free AI reviews to start, with no key. For private repos or more volume, save your own provider key in the panel, or connect a runner.

A private repo with neither a key nor a runner still gets a rules-only review (no AI reads the code), and so does a public repo once its free reviews for the month are used up. The comment carries this note:

Rules-only review: no AI provider is set up for this repo. Public repositories get free AI reviews to start, within a monthly limit. For private repos or more volume, save your provider key in the MergeJudge panel and set provider.type and provider.model in .mergejudge.yml, or connect a runner.

Full panel walkthrough: Getting started.

What permissions the App asks for, and why

Permission	Why
Pull requests: write	Summary comment, line comments, optional approvals
Checks: write	The mergejudge/lane check run
Issues: write	Feedback and /mergejudge learn comments
Contents: write	Only the mergejudge-learning branch, mergejudge/proposal-* PRs and the panel's setup branch mergejudge/setup-config, enforced in code
Metadata: read	Required by GitHub

MergeJudge doesn't merge pull requests itself. If you turn on approval.mode: auto-merge-only, it asks GitHub to auto-merge auto-lane PRs once your branch's protection rules (such as required checks or reviews) are met. MergeJudge never pushes commits to your default, main, master or release branches. Config is always read from the base branch. See the security model and Approvals.

Add the config file (the panel can open the PR)

A repository needs a .mergejudge.yml on its default branch. Every key is optional. You can write the file by hand (config reference), or let the panel open the pull request:

1. A repo with no .mergejudge.yml shows Set up. On Overview, the Finish setup card lists the first repos that need it.
2. Choose a review mode (diff, context or deep), an AI provider, optional protected paths, and whether learning is on. Check the preview.
3. Choose Open pull request. The panel opens a pull request from mergejudge/setup-config that adds the file. It never merges that pull request. You read it and merge it yourself.

Only people with write access to the repo on GitHub can do this. If the panel cannot open the pull request, it shows the file to copy and a link to create it on GitHub. To change review mode, the provider, protected paths, learning or the code-auto switch later, use Edit settings. It opens or updates a pull request on mergejudge/setup-config and never merges it. Details: Getting started.

The file is read from the pull request's base branch tip (falling back to the base commit), never from the pull request head, so a pull request cannot change the rules that review it. Policy files such as AGENTS.md and REVIEW_POLICY.md are read from the base branch as well (policy files).

A minimal file for the hosted service:

# .mergejudge.yml
provider:
  type: anthropic           # anthropic | openai | zai | openai-compatible
  model: your-model-name    # example; use whatever your provider offers

Name the key in the panel like the provider's key name (for example ANTHROPIC_API_KEY), or set provider.api_key_env to the name you used. See LLM providers.

On the hosted service, pick diff or context. Deep mode with a hosted code index is not offered. A deep setting on a hosted repo without a runner runs as context. A runner or the Action can run deep.

# .mergejudge.yml
review:
  mode: context        # diff | context  (deep needs a runner or the Action)

What you see on a pull request

A review posts:

• one sticky comment (edited in place) with lanes, reasons, rubric results and a split suggestion;
• line comments on the exact diff lines for model and rubric findings, at most 20 findings per review;
• a mergejudge/lane check run.

Lane	Meaning	Check run
auto	low risk, can go straight through. Not a guarantee; branch protection and required checks still apply.	success
review	a human must look	neutral
block	do not merge	failure

By default, auto is for paths such as docs/**, **/*.md, **/*.css and public/**, and only when at most 200 lines changed. Code files stay on review unless you turn on lanes.code_auto. The model, rubrics and policy files can only raise a lane (one opt-in exception: lanes.code_auto). If the model call fails or returns invalid JSON after one repair retry, MergeJudge falls back to rules-only and says so. The full path rules are in Lanes and rules and How it works.

Auto is a lane, a label on the pull request. MergeJudge doesn't merge pull requests itself. If you turn on approval.mode: auto-merge-only, it asks GitHub to auto-merge auto-lane PRs once your branch's protection rules (such as required checks or reviews) are met. If your own automation merges on this label, those merges are your decision.

Make the lane a required check

Make mergejudge/lane a required check in branch protection if you want block to stop merges. In the branch protection rules for the branch pull requests merge into, require the status check named mergejudge/lane. A block lane is the failure conclusion.

The review lane means a human must look. human_approvers is shown in the comment as guidance. Enforce human counts with branch protection. Approvals are off by default. See Approvals.

Where your code goes with the App

Code is used only to run the review and is deleted afterwards (runner jobs within about 48 hours). Review findings, which can quote short lines of code, are kept for a limited time. Details: https://mergejudge.si/privacy

See also Privacy.

How you run the review	Where the AI step runs	What is sent
Hosted App, your key	The hosted service calls your AI provider with your key	The diff and your policy files. In context mode, related code as well. Deep mode with a hosted code index is not offered
Runner, diff, context, or deep context built by the hosted service	Your machine (Claude Code, Codex or GLM)	The hosted service passes the pull request diff, policy files and related snippets to the runner through its job queue. With AI review on, code is sent to your own AI provider
Runner, deep-local (review.mode: deep and runner.code_source: local)	Your machine, reading your own git clone	The job carries no code. The hosted service still reads the pull request diff from GitHub to run the rule checks. With AI review on, your machine sends code to your own AI provider
GitHub Action	Your GitHub Actions runner	The Action does not call the hosted service. With a key, the diff goes to your AI provider, and in context or deep mode related code does too. With no key, only the rules run

Prefer your own GitHub App identity in the Action?

The Action can post as a GitHub App you control. Pass app_id and app_private_key (inputs). With both set, the Action mints an installation token and uses it for GitHub API calls. If creating that token fails, the Action warns and falls back to github_token.

# .github/workflows/mergejudge.yml
- uses: gauravsharmaGG/mergejudge-runner@v1
  with:
    app_id: ${{ secrets.MERGEJUDGE_APP_ID }}
    app_private_key: ${{ secrets.MERGEJUDGE_APP_PRIVATE_KEY }}

Approvals are off by default. In the Action, approval.mode: bot-approve needs app_id and app_private_key. With only the workflow token, that approval is skipped. The hosted App approves as mergejudge[bot]. See Approvals.

Checklist

1. Install the GitHub App and pick the repositories.
2. Sign in to the panel. Public repos get free AI reviews to start, with no key. For private repos or more volume, save a provider key or connect a runner. A private repo with neither gets a rules-only review.
3. Optionally add .mergejudge.yml on the default branch to change the settings. The panel can open the pull request from mergejudge/setup-config. Merge it yourself.
4. Open a pull request and read the lane, the summary comment and the mergejudge/lane check.
5. To have a block lane stop merges, make mergejudge/lane a required check in branch protection.