Surmado Code Review: Configuration (surmado-code-review.yml)

Reading time: 3 minutes

TLDR

Drop a surmado-code-review.yml file into your repo’s .github/ folder to control when and how Surmado Code Review runs. Six keys cover the common cases: what triggers a review, whether drafts are included, which language the review is written in, the path to your STANDARDS.md, and the label that gates reviews when trigger mode is label-based. You own the file in your repo, just like STANDARDS.md — or put it in your org’s .github repo to apply the same defaults everywhere.

---

Where the file lives

Commit the config to .github/surmado-code-review.yml at the root of any repo connected to Surmado Code Review. If it isn’t there, Scout falls back to surmado-code-review.yml in your organization’s .github repo (the same place you’d put a shared STANDARDS.md). If neither exists, Scout uses the defaults below.

Example

# .github/surmado-code-review.yml
auto_review_on_open: true
auto_review_on_push: true
review_drafts: false
language: en
standards_path: .github/STANDARDS.md
trigger_label: surmado-code-review

---

Config options

Key	Type	Default	What it does
auto_review_on_open	boolean	true	Run a review when a pull request is opened, reopened, or marked ready for review.
auto_review_on_push	boolean	true	Run a review on every new push to an open pull request. Turn off if you only want reviews on open.
review_drafts	boolean	false	Include draft pull requests. By default Scout waits until a PR is marked ready for review.
language	string	en	Language of the review output. Supported: en, es, fr, pt, ja, it, de.
standards_path	string	.github/STANDARDS.md	Path (from repo root) to the standards file Scout reviews against. Change it if your STANDARDS lives elsewhere.
trigger_label	string	surmado-code-review	Label Scout watches when your org sets trigger_mode: labeled. Cosmetic — lets repos use their own label name.

You can also kick off a review manually by commenting /rerun-review on an open PR, regardless of config. Manual reruns are capped at 3 per hour per PR to prevent accidental loops.

Org-only setting: trigger_mode (which PRs get reviewed across the whole org — all vs labeled) is managed by org admins in the Surmado app, not via this YAML. A repo contributor can’t override an org’s “labeled” restriction by dropping a YAML in their repo.

---

Three ways to change it

The config file is just a file in your repo. You can edit it however you usually edit files.

Ask Scout

Open Surmado Code Review in the app and tell Scout what you want to change (“only review when I open a PR, skip drafts”). Scout drafts the change, shows you the diff, and commits it to your repo once you approve.

Edit it yourself

Open .github/surmado-code-review.yml in your editor, change the value, and commit. Scout picks up the new config on the next PR event.

Use an AI coding agent in GitHub

If you use an AI coding agent (Claude Code, Copilot, Cursor, etc.), point it at .github/surmado-code-review.yml and tell it what you want. It can open the PR for you. Your config change goes through the same review flow as any other code change.

---

Repo-level or org-level

You have two options, and they follow the same pattern as STANDARDS.md:

• Per repo: commit .github/surmado-code-review.yml to the repo being reviewed. Applies to that repo only.
• Org-level default: commit surmado-code-review.yml to your organization’s .github repo (e.g. github.com/acme/.github). Applies to every repo under that org that doesn’t have its own config.

If both exist, the repo-level file wins. You can also leave the file out entirely and run on the built-in defaults.

---

Common recipes

Only review on open, not on every push

auto_review_on_open: true
auto_review_on_push: false

Include draft PRs

review_drafts: true

Get reviews in Spanish

language: es

Point to a non-standard STANDARDS path

standards_path: docs/engineering/STANDARDS.md

Pause automatic reviews (manual only via /rerun-review)

auto_review_on_open: false
auto_review_on_push: false

---

Next Steps

Surmado Code Review FAQ | Get started with Code Review