PR Aura guide

PR Aura is not meant to evaluate anyone's performance. Aura counts reviews under the rules you set, not the value of someone's work. See the terms.

• Quick start
• Configuration
• Earning and spending aura
• Modes: soft and hard
• What you see on a pull request
• Commands
• Members and roles
• FAQ

Quick start

1. Install the app on your organization and pick the repositories. Include the .github repository if you want to configure PR Aura.
2. Done. PR Aura starts with the balanced template in soft mode: it informs, never blocks. Every member gets an initial balance the first time they take part.
3. (Optional) Add .github/pr-aura.yml to the default branch to tune the rules.
4. (Optional) Switch to hard mode to block merges without enough aura. See Enable hard mode.

Configuration

Rules live in one file per organization: .github/pr-aura.yml in your organization's .github repository (for a personal account, <you>/.github). PR Aura reads it only from the default branch.

• The file only lists what you change: template sets the base values and every other key overrides them.
• If the file or the repository is missing, the balanced template applies.
• If the file is invalid (unknown keys, wrong values, larger than 64 KB, YAML aliases), the balanced template applies and the bot lists the problems on the merged PR.

template: balanced          # balanced | strict
currency: aura
mode: soft                  # soft | hard
initial_balance: 40         # integer >= 1
rewards:                    # integers >= 0; 0 turns a review type off
  approve: 10
  changes_requested: 10
  comment: 3
size_multipliers:
  S: { max_lines: 100, multiplier: 1 }
  M: { max_lines: 500, multiplier: 1.5 }
  L: { multiplier: 2 }
merge_cost: 20              # integer >= 1
grant_limit_factor: 10      # max aura per grant = merge_cost × factor
size_ignore: []             # extra glob patterns that do not count toward size
reward_reviews_on_bot_or_exempt_prs: true
admins: [your-tech-lead]    # defaults to organization owners
excluded: []                # outside the economy (all [bot] accounts are excluded by default)
exempt: []                  # merge for free, still earn by reviewing
leaderboard_repo: .github   # repository that holds the leaderboard issue

The leaderboard repository must be private: the app never posts the leaderboard in a public repository.

Only admins can change the economy

A change to .github/pr-aura.yml takes effect only when an admin applies it to the default branch, by pushing it or by merging the PR that contains it. Admins are checked against the currently active config, so nobody can add themselves to admins and approve their own change. A change applied by someone else is rejected, the active rules stay and the bot comments on the merged PR.

Recommended: protect the file with GitHub's own tools too. Add it to CODEOWNERS and require code owner review:

# .github/CODEOWNERS
.github/pr-aura.yml @your-org/admins

Earning and spending aura

• Reviewers earn when the PR they reviewed merges. If it is closed without merging, nobody earns or pays.
• One reward per reviewer per PR, for the best review type: approve > request changes > comment. There is no limit on how many PRs you review.
• "Comment" means a review submitted as Comment (inline code comments included). Plain comments in the Conversation tab do not pay.
• Reward = max(1, round_half_up(base × size multiplier)). Example: approve on a size M PR = 10 × 1.5 = 15.
• Size is measured at merge time. Lockfiles, files marked linguist-generated in .gitattributes and size_ignore patterns do not count.
• Authors pay merge_cost when their PR merges into the default branch. Merges into other branches move no aura.
• Balances can go negative, and aura is always a whole number.

Modes: soft and hard

The queue in hard mode

In hard mode, your balance covers your open PRs oldest first. With 20 aura and a merge cost of 20, you can merge 1 PR; the others wait in line. Drafts are not in the queue. A blocked check shows Needed to unblock: how much aura you need to cover that PR. To unblock it, review PRs to earn aura, convert older PRs to draft, or ask an admin for /aura grant or /aura bypass.

The check updates by itself whenever your balance or your queue changes. If it looks stale, click Re-run on the check or comment /aura recheck.

Enable hard mode

1. Set mode: hard in .github/pr-aura.yml (an admin must apply it).
2. In the repository, go to Settings → Rules → Rulesets (or Branches → Branch protection) for the default branch.
3. Add PR Aura as a required status check. Without this step, the check shows red but GitHub does not block the merge.

What you see on a pull request

Commands

Write commands as a normal comment in the Conversation tab of a PR, or in an issue. Inline code comments and review bodies are ignored. Put several commands on separate lines of one comment (up to 10).

Give aura (admins)

• N is a non-zero whole number. Use a negative number to correct a mistake.
• Max per grant: merge_cost × grant_limit_factor (200 with the defaults), in either direction.
• The user must have access to the repository and must not be excluded. Admins cannot grant themselves.

Welcome to the team!
/aura grant @ana 50
/aura grant @diego 50

Merge without paying (admins)

/aura bypass is for urgent PRs such as hotfixes. The check passes, the author pays nothing, reviewers are still paid, and the bypass is recorded with the admin's name. The bot adds the aura-bypass label; if anyone else adds that label by hand, the bot removes it.

Check the setup (admins)

/aura doctor checks the config, the installation, the leaderboard and the health of the economy, and in hard mode whether the check is required. It also shows the median time to first review over the last 28 days next to the one before installing. /aura doctor fix also republishes missing checks and comments, reloads the config, measures that baseline if the install could not, and proposes a corrected pr-aura.yml with a link to edit it.

Members and roles

Roles come from .github/pr-aura.yml; changing the file changes roles right away.

A person joins the economy, with initial_balance, the first time they open, review or receive aura.

FAQ

Can I merge with a negative balance? In soft mode, yes. In hard mode, no: review PRs, or ask an admin for /aura grant or /aura bypass.

I reviewed several PRs. Why am I still blocked? Rewards are paid when the reviewed PRs merge. They show as pending until then.

Do bots earn aura? No. Accounts ending in [bot] are excluded. Whether reviewing a bot's PR pays is set by reward_reviews_on_bot_or_exempt_prs (on by default).

Does a review after the merge count? No. Only reviews submitted before the merge are paid.