Docs · Quickstart

From install to
first review.

Install the app, pick the repositories and open a pull request. The first review arrives in about a minute and a half.

Updated 4 Nov 2026 · v3.8

Install

Firstpass is an app on your code host. An organisation owner installs it once; nothing changes in your pipelines and there is no agent to add to CI.

Open the Firstpass page on your host’s marketplace and choose Install.

Pick the organisation. You can start with a single repository.

Approve the permissions: read access to code and pull requests, write access to comments and checks.

If you prefer the terminal, the CLI does the same and writes a starter rules file into the repository:

terminal

Copy

npx firstpass init

# Signed in as ines@northlane.example

# Organisation northlane

# Repositories payments-api, web-app

# Wrote firstpass.yml

# Done. Open a pull request to get your first review.

Permissions

Firstpass never asks for admin access and cannot push to protected branches. A suggestion you apply is committed to the pull request branch under your name.

Choose repositories

Reviews run only on the repositories you select. Add or remove them at any time from Settings, then Repositories, or keep the list in code:

terminal

Copy

npx firstpass repos add northlane/search

npx firstpass repos list

# payments-api TypeScript pnpm test active

# web-app Ruby bundle exec rspec active

# search Go go test ./… active

How the build is detected

Firstpass reads the lockfile and the usual build files to work out how to build and test a repository. When it guesses wrong, state the commands in firstpass.yml:

firstpass.yml

Copy

build: pnpm install --frozen-lockfile && pnpm build

test: pnpm test --changed

timeout: 10m

First review

Open a pull request as you normally would. Firstpass receives a webhook from the host, checks out the branch in an isolated container, builds it and runs the tests that cover the changed lines.

webhook payload (shortened)

Copy

POST /hooks/github

X-GitHub-Event: pull_request

{

“action”: “opened”,

“number”: 4127,

“repository”: { “full_name”: “northlane/payments-api” },

“pull_request”: { “head”: { “sha”: “7c1e9f2” }, “base”: { “ref”: “main” } }

}

The review has three parts:

—

A summary at the top of the pull request: risk, the number of comments by severity and whether it is safe to merge.

—

Comments on the exact lines, each with the evidence: a failing test, a measured cost or the rule it breaks.

—

A suggestion where the fix is small and the tests pass with it. Apply it in one click or dismiss it.

Ask for another pass

Every push to the branch is reviewed again. To ask for a review without pushing, comment /firstpass review on the pull request.

Rules file

firstpass.yml sits in the root of the repository. Rules are plain sentences; Firstpass applies each one to every pull request and cites it in the comment.

firstpass.yml

Copy

rules:

- “Money is stored as integer cents, never floats”

- “Every new endpoint needs an auth test”

- text: “No direct imports from /internal in /web”

paths: [“web/**”]

ignore:

- “**/*.snap”

- “vendor/**”

severity: block_on_bug

Writing a rule that works

—

One rule, one sentence. Split a rule that contains the word “and”.

—

Say what must be true, not what to avoid in general: “Dates are stored in UTC” beats “Be careful with time zones”.

—

Limit a rule to a folder with paths when it only makes sense there.

Limit

A repository can hold up to 40 rules. Past that, comments start to read like a linter and people stop reading them.

Severity

Every comment has one of three levels. The severity key decides which of them hold the merge.

Level

Meaning

Default

BLOCKING

Firstpass can show the failure: a failing test, a leaked secret, a broken rule.

Holds the merge

SHOULD FIX

A likely problem with a measured cost, such as an N+1 query.

Reported

NIT

Small and optional.

Hidden

firstpass.yml

Copy

# block_on_bug only BLOCKING holds the merge (default)

# block_on_all BLOCKING and SHOULD FIX hold the merge

# report_only nothing holds the merge

severity: block_on_bug

show_nits: false

Self-hosted runners

On Enterprise, builds and tests can run in your own cloud account. Source code stays inside your network; only the review text leaves it.

terminal

Copy

docker run -d --name firstpass-runner \

-e FIRSTPASS_RUNNER_TOKEN=fpr_your_token_here \

-e FIRSTPASS_REGION=eu \

-v /var/run/docker.sock:/var/run/docker.sock \

firstpass/runner:3.8

A runner needs outbound HTTPS to runners.firstpass.example and nothing inbound. Size it at 4 vCPU and 8 GB of memory for each review you want to run at the same time.

Tokens

Create runner tokens in Settings, then Runners. A token is shown once; store it in your secret manager, not in the repository.

FAQ

Does a review use our CI minutes?

No. Firstpass builds in its own containers, or in your runners on Enterprise. Your pipelines run as before.

What happens to the code after a review?

The container and the checkout are destroyed when the review is posted. Build snapshots are kept for 7 days to speed up the next review and can be switched off.