Steward
Sign in

Documentation › Contributor guides

Contributing to a Steward repo

If you just opened a pull request and saw a comment like "Steward verdict: 78 / 100 — amber" appear on it, this doc is for you. You don't need to know what Steward is to use the repo, but knowing what the verdict means makes the back-and-forth a lot less mysterious.

What you'll see

When you push a PR against a repo that has Steward installed, three things happen automatically in the background, none of which require any action from you:

1. Gate check runs appear

Within seconds of opening the PR, GitHub starts showing one or more check runs prefixed with Steward —. The common ones:

  • Steward — DCO — checks every commit has a Signed-off-by: trailer ("Developer Certificate of Origin"). Common on Linux-style projects.
  • Steward — CLA — checks your account has signed the repo's Contributor License Agreement.
  • Steward — SARIF — surfaces any linter errors the repo's CI uploaded as Static Analysis Results Interchange Format (SARIF) artifacts.

Each check run shows ✅ (passed), ❌ (failed), or — (neutral / not applicable). If one fails, read its detail page — that's where the actionable feedback is. We'll cover remediation in the Fix a DCO failure and Sign a CLA on a Steward repo guides.

2. A verdict comment appears

About 20 seconds after you open or push, a comment from the Steward GitHub App lands on the PR. It looks like:

Steward verdict: 78 / 100 — amber

> One-sentence headline describing the PR.

### Correctness — 85
Source files changed alongside test files; ratio above 0.33.

### Security — 65
Touched internal/auth/middleware.go with paired test changes.

### Complexity delta — 55
432 LoC across 18 files. On the boundary between medium and large.

### Docs alignment — 90
docs/auth/middleware.md updated alongside the code.

### Governance alignment — 75
governance.pxf present; touched files map to the `auth` domain.

This is the per-PR evaluation — a deterministic per-file scorecard with five dimensions, plus a short paragraph per dimension written by a Large Language Model (LLM). It's advisory. It doesn't block your merge by itself.

Read the verdict carefully. It often catches things human reviewers will ask you about anyway: "did you remember the tests?", "this is a big diff — can you split it?". If you respond to the verdict's points proactively, the PR review goes smoother.

A full reading playbook from the contributor angle is at Read the verdict on your PR.

3. The repo's gates run

The check runs from step 1 are the visible part of a broader gate system — DCO, CLA, complexity ceiling, coverage floor, SARIF rules. Each gate is configured in the repo's .steward/governance.pxf and either blocks the merge or flags for attention. A blocking gate's check-run failure means GitHub branch protection won't let the PR merge until fixed.

The full gate catalogue is at Gates: DCO, CLA, complexity — useful if a check-run failure is unfamiliar and you want to understand the rule behind it.

What's automatic vs what you can ask for

Steward fires automatically on:

  • pull_request.opened — the verdict comment + gate check runs land.
  • pull_request.synchronize — every push to the PR re-runs the gates and updates the verdict.

You can ask for an evaluation explicitly by commenting on the PR:

/steward evaluate

When this is useful:

  • The original evaluation arrived as failed and you want to retry after the upstream issue resolved.
  • The repo is on the Community tier, where automatic per-PR evaluation is opt-in. The slash command works regardless of tier.
  • You amended the PR significantly without pushing (e.g., closed/reopened) and want a fresh verdict.

Other slash commands for contributors:

Command What it does
/steward evaluate Re-runs the per-PR evaluation.
/steward check-reputation Posts your reputation across the touched domains.
/steward sandbox-me Asks for a "sandbox issue" — see Sandbox issues.

Full reference at Using /steward slash commands.

Reputation — yes, you have one

If you've contributed to the repo before, Steward has a per-domain reputation score for you. The verdict comment sometimes mentions it:

alice — api domain: 12.4 reputation (above approval threshold; eligible for self-merge).

Reputation comes from merged PRs in the repo's governance.pxf-defined domains. It decays over inactivity. It's per-domain, not per-repo — your reputation in the api domain accumulates across every Steward-governed repo that has a domain named api. Pure scoring; no badges, no leaderboard.

Higher reputation in a domain typically means you can self-merge PRs that only touch that domain (governed by the domain's approval_threshold); below the threshold, you need a reviewer above it to approve.

If the repo is configured with sandbox-issue intake, your first reputation points come from claiming and finishing a sandbox issue — see Sandbox issues.

Deep dive on the mechanics: Reputation as a contributor.

What Steward sees

Worth knowing if you're privacy-conscious:

  • Public repo + public PR: Steward sees the same data GitHub shows anyone — diff, commit messages, file paths.
  • Private repo + your PR: Steward sees the same data the maintainer's installation granted it — same scope, just not public-readable.
  • Your GitHub identity: login, email (if public on your GitHub profile), avatar. Linked to your app.users row if you ever sign in at steward-dev.ai.
  • Per-PR LLM call: the LLM sees the diff + the repo's governance.pxf for the prose generation. It does not see your other repos' content.

Nothing is sent to the LLM provider beyond what the per-PR scoring needs. The provider's data-retention policy applies (Anthropic by default; the repo's maintainer can override with a Bring-Your-Own-Key configuration).

You can manage your Steward-side data — including account deletion — from the steward-dev.ai account surface. See Your account + your data.

What this isn't

Worth being explicit:

  • Not a merge gate by itself. The verdict is advisory. Gates can block; the verdict doesn't.
  • Not a reviewer. Steward writes a verdict and runs gates. A human still has to approve the PR (or you self-merge if reputation allows it).
  • Not transparent to maintainers vs contributors. The verdict you see is the verdict the maintainer sees. Reputation scores are visible on both sides; sandbox-issue intake is configured by the maintainer + claimed by you.

What's next