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

Reading time: 4 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. Two more keys tune the advisory dependency/import check that catches missing or AI-invented packages. 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
dependency_check_enabled: true
dependency_check_ignore: []

---

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.
dependency_check_enabled	boolean	true	Flag imports of packages that aren’t in your manifests, or that don’t exist on npm or PyPI (missing or AI-invented dependencies). Set to false to turn this advisory check off. The secret/credential scan is separate and always runs.
dependency_check_ignore	list	[]	Import names to always treat as internal, so the check never flags them. See Tuning the dependency check for the exact-vs-prefix format.

You can also kick off a review manually by commenting /rerun-review on an open PR, regardless of config. A rerun re-reviews the PR’s current code from scratch, including a fresh read of your STANDARDS.MD and this YAML, so it’s the fastest way to see the review re-graded after you tune either file. It’s also the retry button when a review errored. Each rerun costs 1 PR credit, and manual reruns are capped at 3 per hour per PR to prevent accidental loops. Scout reacts with a rocket when the rerun is accepted and an hourglass when it’s on cooldown.

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.

---

Tuning the dependency check

Alongside the review, Surmado Code Review runs a fast, advisory check on the imports your PR adds. It flags two cases:

• Missing dependency – the package exists on npm or PyPI, but it isn’t in your manifest (package.json, pyproject.toml, requirements.txt, and so on). Add it, then re-push.
• Hallucinated package – the package doesn’t exist in the registry at all. Usually a typo, or something an AI coding agent invented.

The check is monorepo-aware (it resolves each file against the nearest manifest) and it already skips things that aren’t real packages: TypeScript and JavaScript path aliases declared in tsconfig.json or jsconfig.json (@/components, and the like), node: built-ins such as node:test, and relative imports. For most repos you never have to touch it, and it’s advisory only – findings never block a merge.

When something is wrongly flagged: dependency_check_ignore

If the check flags an internal import it can’t detect on its own – a bundler-only alias (Vite, webpack, or a Jest moduleNameMapper entry), a workspace package, or a baseUrl bare import – add it to dependency_check_ignore and it won’t be flagged again.

One rule decides what each entry matches, and it’s the part worth reading twice:

A trailing / makes the entry a prefix. Without a trailing /, the entry is an exact match.

Entry in the list	What it silences	Reach for it when
@myorg/	every import that starts with @myorg/ (@myorg/ui, @myorg/db, and so on)	a whole internal scope or set of workspace packages
~assets	exactly ~assets, and nothing else	one specific alias
left-pad	exactly left-pad, and nothing else	one specific package name

So @myorg/ (with the slash) covers your entire org scope, while @myorg (no slash) would only match an import of literally @myorg. For a scope or an alias root, you almost always want the trailing slash.

dependency_check_ignore:
  - "@myorg/"      # any @myorg/* workspace package
  - "~assets"      # a Vite alias that points at src/assets
  - "@/generated"  # a single generated-code import

Two things to remember:

• Quote every entry. YAML treats a leading @ as reserved, so - @myorg/ without quotes is an error. Write - "@myorg/" instead.
• Entries apply to both JavaScript/TypeScript and Python imports.

If you’d rather not maintain a list, turn the whole check off with dependency_check_enabled: false. Your secret and credential scan is a separate check and keeps running either way.

---

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

Stop flagging an internal scope or alias as a missing dependency

dependency_check_ignore:
  - "@myorg/"

Turn the dependency check off entirely

dependency_check_enabled: false

---

Next Steps

Surmado Code Review FAQ | Get started with Code Review