Steward
Sign in

Documentation › Get started

Install Steward + your first PR

A 15-minute walkthrough that takes you from "I just heard about Steward" to "my first PR has a verdict." This is the maintainer-fast-path — single repo, personal install, no billing decision needed. If you're sizing Steward up for an org (with billing, Single Sign-On (SSO), multiple repos), use Set up your sponsorship instead.

Before you start

You need:

  • A GitHub account.
  • A repo you have write access to. Public or private both work; for the smallest mental load on day one, pick a small public repo with some recent PR activity.
  • 15 minutes.

You don't need:

  • A credit card. The Community tier is $0 and the install flow doesn't ask for one.
  • A pre-existing governance.pxf. We'll write a minimal one in step 2.
  • Any local Steward CLI install. Everything happens through the GitHub App + the steward-dev.ai web UI.

1. Install the GitHub App

Steward integrates with GitHub via a standard App installation. From your dashboard:

  1. Sign in at steward-dev.ai — the sign-in flow uses GitHub OAuth.
  2. Click Install Steward on the empty-fleet card. GitHub takes over the flow.
  3. Pick the account to install on. For the maintainer-fast-path, install on your personal account (not an organization) — an org install is the sponsor-fast-path.
  4. Repository access: pick Only select repositories and choose one. You can add more later; the day-one discipline is "small surface, get a verdict, then expand."
  5. Permissions review: read the requested permissions and click Install.

GitHub returns you to /app. The repo appears in the fleet table within a few seconds — the webhook delivery is what lights it up. If it doesn't appear after 30 seconds, hard refresh; if it still doesn't show, the installation may have failed silently — check Manage installations on GitHub and re-install if necessary.

2. Create your governance.pxf

The first PR Steward sees triggers an evaluation. To get a meaningful verdict, the repo needs a governance.pxf file at .steward/governance.pxf on the default branch.

The fast path: open your repo's governance editor (/app/governance) and use the posture wizard. Pick how your project works — welcoming a community, a disciplined internal team, company-backed open source, or a community-governed project — answer two or three questions, and Steward writes the file: a version-pinned preset supplying the posture, plus a few lines that are genuinely yours. Everything stays adjustable in the editor afterwards.

The manual path, if you'd rather start from a file you typed yourself — the smallest useful one:

domains: [
  {
    name: "everything"
    path_globs: ["**/*"]
    max_cyclomatic_complexity: 15
  }
]

Commit it to the default branch and push.

Skipping this step is OK on day one — Steward falls back to a permissive baseline that scores every PR but doesn't reflect project-specific intent. The fleet dashboard surfaces a "no governance.pxf" badge to remind you. The verdict on your first PR will still appear; it just won't say much that your codebase couldn't have predicted.

The full reference is at governance.pxf + domains, and the step-by-step guide that walks through a real repo is at Write your first governance.pxf.

3. Open a pull request

Open any PR against the default branch. The pull_request.opened webhook fires; Steward enqueues an evaluation; the worker picks it up within seconds.

What happens on the first PR

Two things fire in parallel:

  • Gates run immediately — Developer Certificate of Origin (DCO), Contributor License Agreement (CLA), complexity, Static Analysis Results Interchange Format (SARIF). Each gate posts a GitHub check run (e.g. Steward — DCO). These are deterministic; they finish in seconds. See Gates: DCO, CLA, complexity for what each gate checks.
  • Per-PR evaluation runs asynchronously — the deterministic per-PR scorecard runs first, then the Large Language Model (LLM)-grounded prose. Total time-to-verdict is usually under 20 seconds; the verdict lands as a comment on the PR.

On the Community tier the per-PR evaluation is opt-in; on Pro / Team / Business it runs by default. To trigger one on demand from any tier:

/steward evaluate

Drop that as a comment on the PR. Steward enqueues a fresh evaluation and posts the verdict when it's done.

If nothing happens after a minute

Common causes:

  • The App was installed but not granted access to this repo — check the installation's repo allowlist.
  • The default branch isn't the target branch — Steward evaluates PRs against the default branch only.
  • You're at your daily credit cap — only relevant if you've been hammering the system; check /app/repos for a skipped(budget_exhausted) status on the row.

For any other failure mode, the row at /app/repos/<id>/pulls shows the failure reason; cross-reference Debug a failed evaluation.

4. Read the verdict

Two surfaces show the result:

Surface 1: the PR comment

Steward posts (or updates) a comment on the PR with the verdict. The shape:

Steward verdict: 78 / 100 — amber

> One-sentence headline written by the LLM.

### Correctness — 85
...

### Security — 65
...

The full reading playbook is at Read an evaluation report — including a worked example and the three reasons it's legitimate to disagree with a verdict.

Surface 2: the per-repo PR list

/app/repos/<repo-id>/pulls

One row per PR-evaluation, newest first. Columns: PR + title, author, head SHA, status (queued / running / done / failed / skipped), overall score + colour pill, updated timestamp.

Filter by status to triage: failed is the investigation queue; done + red is your "PRs that scored poorly" sweep for Monday review.

What's next

Pick by what you want to do next:

You want to write better governance.pxf rules

You want to understand how scoring works

You want to think about your contributors

  • Contributor reputation — how reputation accumulates per-domain, decays exponentially, and gates self-merge.

You want to monitor multiple repos

You're sizing Steward up for a team

Something went wrong