Installing the PR Lens GitHub App: what it reads, what it posts, what it never sees

Go to github.com/apps/coldtea-pr-lens, choose the account or organisation, and pick the repositories you want drawn. That is the setup. From then on, every pull request opened in those repositories gets one comment carrying animated architecture and data-flow diagrams, and that comment is rewritten on every push. There is no workflow file to commit and no model key of yours involved; the hosted App runs on Gemini today on our key. It exists because of the wait LinearB measured in its 2026 benchmarks: across 8.1 million pull requests, AI-generated ones sat 4.6 times longer before a reviewer picked them up.

What happens on the first pull request

The App does not draw a change against nothing. It keeps a baseline of the repository, a stored map of the system as the default branch stands, so that a pull request is drawn against the system rather than floating on its own. That baseline is what puts the untouched parts of your architecture on the page in grey next to the parts the change moved.

Building it takes a scan, and the scan takes a few minutes. Where an installation covers three repositories or fewer, the App starts building baselines the moment you install. For a larger installation it would be rude to scan everything at once, so the baseline is deferred to each repository's first pull request. While it runs, a check run called PR Lens says it is creating the first lens for this repository before it draws this pull request.

After that the baseline moves with your default branch. A push to the default branch refreshes it, so the map does not fall a month behind the code.

Which events wake it up

Four kinds of webhook, and nothing else.

A pull_request event when a pull request is opened, reopened, pushed to, or marked ready for review. Drafts are skipped: a draft gets drawn when it stops being a draft, not before, because a diagram of a branch someone is still rewriting is noise.

An issue_comment event, but only an edit, and only when the edited comment is a PR Lens sticky comment on a pull request. That is the checkbox loop. Ticking a view option in the comment re-renders from the stored graph without re-running analysis, which is why toggling is fast and free.

A push event, and only to the repository's default branch. Anything else is dropped.

An installation or installation_repositories event, so the App learns which repositories it can see when you add or remove one.

Every one of those arrives signed, and the signature is verified against the raw body before the payload is parsed. An unsigned or wrongly signed request is rejected with a 401 and never reaches any of the logic above.

What the App reads

To draw a pull request it needs the change and the system the change sits in.

It reads the comparison between the pull request's base and head commits, including the patch for each file. It reads the repository's file tree at both commits. It reads .github/pr-lens.yml from the pull request's head commit. It reads the pull request itself, for the title and to confirm the current head before it publishes. It reads repository metadata: the default branch, and whether the repository is private.

For the analysis run it clones the repository over HTTPS at depth 1, at the head commit. One commit deep. Your history is not fetched, because a diagram of one change has no use for it.

What the App writes

Two things.

One comment on the pull request, created once and updated in place forever after. And a check run called PR Lens, which is how the App tells you it is working, or waiting on a baseline, or has failed, without posting a comment saying so.

That is the complete list. The App does not push commits, does not create branches, does not edit your pull request description, and does not open pull requests of its own. If you are auditing what a bot can do to a repository, the answer here is a comment and a check.

What it never sees

Repositories you did not select. A GitHub App only reaches the repositories you tick on the install screen, and adding one later is a deliberate act on your part. If you install it on three repositories, the other two hundred are invisible to it.

Your history, beyond the one commit it needs. The analysis clone is depth 1 at the head sha.

A model key of yours, because there is not one. The hosted App runs on Gemini today on our key.

The credentials that make the clone work, from inside the analysis sandbox. The installation token is bound to the sandbox when it is created and injected as a request header for github.com, so it is never in the clone URL, never in .git/config, never in the environment, and never in a file the analysis process can read. The provider key is handled the same way. A repository whose contents end up steering the analysis still has nothing to steal.

The permission list is on the install screen

GitHub shows you every permission an App requests before you approve it, with the repositories it will apply to. That screen is the authoritative version, it is shown at install time and again whenever the App asks for more, and it is where you should read the list rather than trusting a blog post to have kept up. I would rather point you at it than restate it here and let it drift.

What I can tell you is what those permissions are for, which is the section above: the reads exist to build the diagram, and the writes are a comment and a check run. If something in the list does not map onto one of those, that is a fair question to raise as an issue on the repository.

One comment, kept correct

The App maintains exactly one comment per pull request. Its state travels in a hidden HTML marker inside the comment body, which is how a later render finds the comment it wrote last time and knows which stored graph to redraw from.

That marker is public text. Anyone can copy it into a comment of their own. So the marker alone is never enough. Only comments the App itself wrote are ever adopted, edited or deleted. The comment's markers are also read by position, with the state marker taken as the last one in the body and an option read only from a line that is actually a checkbox, so text quoted earlier in a thread cannot choose which graph a re-render reads or silence a toggle.

Latest commit wins. A run checks its commit against GitHub's current head before it does expensive work, and again before it publishes. An older analysis that finishes last is discarded rather than overwriting a newer diagram. If the head cannot be confirmed at all, publishing does not proceed: the run retries and finalises once GitHub answers.

Creating that first comment is exclusive. A render either holds a lease or waits for whoever does, and straight after creating, the run lists its own comments again and collapses any duplicate onto the oldest one. The engineering behind that is a post of its own: how PR Lens keeps exactly one comment per pull request.

Rendered SVGs live at content-hashed keys, because GitHub proxies comment images through a cache that never revalidates. A new render is a new URL, so the picture in the comment is always the one that matches the code.

Fair use

The App caps how much analysis a repository or an installation can trigger in an hour: 40 analyses per repository, and 200 across an installation. The installation limit is checked first.

The cap exists because a synthetic flood of pull requests is a bill, and free for open source only works if the free part cannot be turned into a denial of wallet. A pull request that hits the limit gets a comment saying it was rate limited rather than silence, which is the behaviour I would want as a user. Baseline refreshes are dropped quietly when the limit is hit, because the next push to the default branch will refresh it anyway.

Configuring it

Commit .github/pr-lens.yml. The App reads it from the pull request's head commit, so a change to the config takes effect on the pull request that changes it.

schemaVersion: 0.1.1
github:
  comment:
    collapsed: true

github.comment.collapsed defaults to false. Set it to true and the diagrams and details start closed, which teams with a busy pull request template tend to prefer. Drawing still runs; only the presentation changes. It is also the only setting the hosted App reads: the correction map in the same file, the renames and exclusions and lane pins, is applied by the CLI and the Action when they draw. Every option that exists is in configuring PR Lens.

Private repositories

It is free for open source. If you would rather not install anything on a repository, the skill runs it for free through the coding agent you already have open, on the model that agent already uses.

A pull request in a private repository is not readable by the public web. The share page for one requires a signed link tied to the graph's current head commit, and the App re-checks a repository's visibility against GitHub rather than trusting a cached answer for long, so a repository flipped to private drops out quickly. What gets stored, and where, is the subject of what PR Lens does with your code.

If the hosted App is not what you want

Some teams cannot send a diff to an App they do not run. That is a reasonable position, and the answer is the PR Lens GitHub Action: the same pipeline inside your own CI, on your own key, with the diff going to the provider you name and nowhere else. You give up the checkboxes and the canvas link, because an Action cannot hold state between runs.

The four ways to run PR Lens, and which one suits which team, are laid out in what is PR Lens.