How to install our GitHub App

About the app

august posts a product and UX review on every pull request. A panel of simulated customer twins reads the change and comments as those customers would.

How it looks on a pull request:

1. A comment appears saying "Analysing this commit".
2. The same comment is then edited to hold the finished review.
3. When the next commit lands, the older review collapses as outdated.

The review is advisory. It never blocks a merge.

Prerequisites

1. A fully provisioned august organization with twins trained.
2. Someone who can install a GitHub App on the account that owns the repository is added as an 'admin'/'owner' on august

Steps

1. Find the august GitHub App here : https://github.com/apps/august-pr-review. Click on 'Configure'

   

2. Select the repositories you want to give access to.

   

   

3. After selection, you'd be redirected to august where you'll select the org to source the twins for these reviews (in case you have access to multiple orgs)

   

4. Final step would be to add an august.yaml file in the root of the repo you'd want reviews for (more in a dedicated section for august.yaml below)

   

5. To check if it works fine push a commit that changes something a person would notice - copy, a component, an interaction, an error or empty state - in a path the rules match.

   1. Within about a minute, a comment saying "Analysing this commit".
   2. A minute or two later, the same comment holds the finished review.
   3. On the next commit, the old review collapses and a new one appears.

august.yaml

This file tells august which files to review, and whose eyes to review them with. Without it nothing happens.

Where it goes

1. The root of the repo, named exactly august.yaml.
2. It has to be on your default branch. august reads it from the base branch of each PR, so it starts working on PRs opened after it lands on main. Nothing needs reconnecting.
3. The PR that adds august.yaml won't get a review itself, because the file isn't on the base branch yet. That's expected, not a fault.

What it looks like

org: Acme Product
default:
  audience: People who use Acme day to day.
paths:
  - match: "apps/console/**"
    audience: >-
      Platform engineers configuring Acme in the web console.
  - match: "packages/sdk-typescript/**"
    audience: >-
      Developers installing and upgrading the TypeScript SDK in their own app.
  - match: "openapi/**"
    audience: >-
      API consumers reading the spec to build an integration.
    priority: 10
panel_size: 3

The fields

1. paths[].match - required. A glob. * stops at a /, ** crosses directories.
2. paths[].audience - plain English describing the people who use this part of the product. This is what picks the twins, so describe people, not code.
3. paths[].segment - use this instead of audience to pin an exact august segment. Every rule needs one of audience or segment.
4. paths[].priority - optional whole number, defaults to 0.
5. panel_size - optional, defaults to 3. Three is also the most any account gets today, so leave it alone unless we have raised your limit. Ask for more than your account allows and august refuses the review and posts a comment telling you so.
6. default.audience and default.segment - optional context. They do not opt unmapped paths into reviews. Only paths does that.
7. org - a label for your own reference. It does not decide whose twins review the repo. The org you picked in step 3 does.

When two rules match the same file

Highest priority wins. If priorities are equal, the longer match wins. If those are equal too, it falls back to alphabetical order.

Two things that will silently break it

1. A mistake anywhere in the file. An unknown key, a misspelled key, a decimal priority, a panel_size above 10, or a rule with neither audience nor segment makes august skip the repo entirely - no review, no comment, no error. If reviews stop right after you edit this file, assume the file is the problem.
2. Paths you never mapped. There is no fallback. A backend-only repo gets nothing until a paths rule covers it. Go, Python, Rust and YAML changes are reviewed only if a rule matches them.

A panel_size between 4 and 10 is a third case, and it is not silent. The file parses, so august reads it, then refuses the review because the number is above your account's limit - and it posts a comment saying exactly that. Set it back to 3 and push again.

Getting an agent to write it for you

Open Claude Code, Codex, or Cursor or any other coding agent at the root of your repo and paste this in:

Write an `august.yaml` file for this repository. It configures august's GitHub PR
review app, which posts a product and UX review on pull requests using simulated
customer personas.

Your job is to work out which parts of this repository are user-facing, and to
describe who uses each part.

First, explore the repository. Identify the distinct surfaces a real person
touches: a web app, a dashboard, a CLI, an SDK, a public API spec, docs, email
templates. Ignore anything no user perceives: tests, fixtures, generated code,
build config, CI, lockfiles, infrastructure.

Then write `august.yaml` at the repository root, using ONLY these keys:

  org          optional string. A label only.
  default:
    audience   optional string
    segment    optional string
  paths        list of rules, each with:
    match      required string. A glob. `*` does not cross `/`, `**` does.
    audience   string describing the PEOPLE who use files under this path
    segment    string naming an exact august segment
               (each rule needs `audience` or `segment` -- at least one)
    priority   optional integer, default 0
  panel_size   optional integer, default 3. Leave it at 3 (see below)

`default` is context only. It does NOT make unmapped paths reviewable. Only
`paths` does that.

Hard rules. Breaking any one of them makes august silently skip the whole
repository, with no error anywhere:
  - No key outside the list above. No extra keys, no misspellings.
  - `priority` must be a whole number, never a decimal.
  - `panel_size` must be a whole number between 1 and 10.
  - Every entry in `paths` must have `audience` or `segment`.

One more rule that fails differently: do not set `panel_size` above 3. Anything
from 4 to 10 parses fine, so the file looks correct, but august then refuses the
review because the number is above the account's limit and posts a comment
saying so. Write 3, or leave the key out.

How to write a good `audience`:
  - Describe people and what they are trying to do, not the code.
    Good: "Support agents triaging refund requests in the admin console."
    Bad:  "React components under src/admin."
  - One or two sentences, in plain language, using words the customer would use.
  - Be specific about the job. "Users" is useless. "Shoppers comparing sizes
    before buying" is useful.

When two rules could match the same file, the highest `priority` wins, then the
longer `match`. Use `priority` only to override a broader rule.

Only map paths where a change would actually be visible to that audience. Fewer,
sharper rules beat many vague ones. Leaving a path out is better than mapping it
to the wrong people.

Worked example. For a repository laid out like this:

  apps/web/           storefront that customers browse and buy on
  apps/admin/         internal console the support team uses
  packages/ui/        shared React components, used mostly by apps/web
  packages/logging/   internal logging helpers, nothing a user perceives
  openapi/store.yaml  public API spec that partners build against
  scripts/, .github/  build and CI tooling
  **/*.test.ts        tests

a good `august.yaml` is:

  org: Acme
  default:
    audience: People who shop on Acme's online store.
  paths:
    - match: "apps/web/**"
      audience: >-
        Shoppers browsing and buying on Acme's storefront, usually on a phone,
        comparing a few products before they check out.
    - match: "apps/admin/**"
      audience: >-
        Acme support agents looking up an order and fixing a customer's problem
        while that customer waits on chat.
    - match: "packages/ui/**"
      audience: >-
        Shoppers on the storefront, since these components render the pages
        they actually see.
    - match: "openapi/**"
      audience: >-
        Partner developers reading the spec to build an integration against
        Acme's API.
      priority: 10
  panel_size: 3

Note what is left out and why. `packages/logging/` has no user-visible surface,
and `scripts/`, `.github/` and test files are never reviewed, so none of them get
a rule. `packages/ui/**` is shared, so it is mapped to the audience it mostly
serves rather than being split. `openapi/**` carries a `priority` so it still
wins if a broader rule is added above it later.

When you are done, show me the file and give one line per rule explaining why you
chose that audience, so I can correct the ones you guessed wrong.

Read what it produces before you merge it. The audience lines are the part that decides review quality, and only you know who your users really are.

Limitations

1. Five automatic reviews per pull request. Later pushes produce nothing at all, with no comment and no error.
2. Two hundred reviews per organization per month.
3. One review per commit. Older ones collapse rather than disappear.
4. Reviews cost no august credits. (for now)
5. Some reviews carry a banner saying the review saw a shortened version of the change. It means part of the input did not fit, usually the surrounding repository context rather than the change itself. The review is still valid.
6. Draft pull requests are skipped.
7. Each finished review invites a thumbs up or thumbs down. Please use it to provide feedback on the reviews.

Some failure modes and likely reasons

1. No review and no error. In order of likelihood:
   1. No august.yaml on the default branch.
   2. No paths rule matches the changed files.
   3. The changed files are all tests, type declarations, or generated output. These are filtered out.
   4. The pull request is a draft, or its title contains WIP.
   5. The pull request already had five reviews.
   6. The change has no user-visible effect. This is normal for a pure refactor.
2. The connect page offers no organization. The user installing isn't an owner/admin of any august org, or the membership isn't active. Reach out to august team for this.
3. The connect page says the link expired. The link would expire after 10 minutes. To unblock, use the retry link on the page
4. The connect page says that GitHub account cannot manage the installation. The user has authorised with the wrong GitHub account. Sign in to GitHub as the right one and retry.
5. The connect page says the installation is already connected. It belongs to another august organization, which august will not name. Uninstall on GitHub and install again to move it.
6. The panel looks wrong for the change. The matched rule's audience describes the wrong people. Refine it, or add a more specific rule with a higher priority.
7. A comment still says "Analysing this commit" for 5+ minutes. Usually one of the twins failed to respond, and an auto-retry mechanism kicks off to produce the review within 15 minutes. To clear it sooner, push a new commit.