Fields
An unavailable
model, or an option the input mode does not support, skips the check with a configuration message in its details. An unsupported reasoning level warns and falls back to low.
Input modes
incremental(default): Recommended for most diff-based checks. Reviews files changed since this agent’s last completed review, each shown as its full PR diff. Saves tokens on later pushes by leaving unchanged files out.full_diff: Sends the entire PR diff on every run. Useful when the agent needs PR-wide context each time; usually uses more input tokens than incremental on later pushes.code_object: Runs a separate agent per changed code object, with up to 20 running concurrently. Use for specialized checks that need focused, parallel review of individual objects. Can be much more expensive because each object runs its own agent.pr_metadata: Sends the title, author, labels, description, and commit messages, without the diff. Use when the task does not need the diff, such as ticket links or title conventions. Often much more token-efficient for these tasks.
input value warns and falls back to full_diff.
An incremental agent’s first run covers all in-scope files. Later runs use its last completed review as the baseline. Skips, errors, cancellations, and incomplete reviews do not advance it. No new in-scope changes means a free, skipped check.
Force-pushes, rebases, a moved merge base, configuration or ignore-rule changes, explicit mentions, and GitHub reruns cause a full review when the prior baseline cannot be reused safely.
pr_metadata uses the same triggers, file-scope rules, and tools as full_diff. Its tools can still inspect code when instructed.
File scope
include selects files; exclude removes them. Patterns without / match at any depth, * matches within one path segment, and ** spans directories.
include overrides repository ignore rules, but not the agent’s exclude. The check warns when it overrides an ignore pattern. Agents without include respect repository ignores.
In every mode, comments on out-of-scope files are dropped. If every file is excluded, no agent runs and no usage is billed.
include/exclude normally produce no check; requiredStatusCheck: true produces a skipped check. Repository ignore rules that exclude everything always produce a skipped check.
Applicability filters
authors, labels, and targets each require at least one match within their list. All configured axes must match. A configured axis replaces the corresponding repository skip rule; omitted axes follow repository settings.
[bot]. Target branches are literal names, with only_default_branch as a special value. Blank entries are ignored and duplicates removed. Front matter filters apply even to explicit mentions and reruns.
Required status checks
conclusion: failure allows a check to fail when it finds a violation; a clean result still reports success. Add the check to GitHub branch protection to make that failure block merging.
conclusion: failure requires input: full_diff, code_object, or pr_metadata. It is unsupported with incremental (the default), which cannot replay an earlier failure verdict.
For scoped checks, also set requiredStatusCheck: true. A selected agent excluded by its applicability or file filters then reports skipped, which GitHub accepts, instead of leaving an indefinitely pending required check.
This option does not schedule the agent. If the feature is disabled, the definition is deleted or renamed, or the event selects another agent, no check is created. Keep branch protection consistent with those settings.
Prerequisite steps
Use names from the PR’s Checks tab. Matching is exact apart from case and applies to individual check runs, not whole workflows. At most 10 distinct names acrosswaitsFor and requires.
lint must pass. Every waited-for result is supplied to the agent.
requires accepts GitHub’s passing conclusions: success, neutral, and skipped. A failed, cancelled, timed-out, stale, or action-required check prevents the agent from running. Use waitsFor when the agent should investigate failures.
Missing prerequisites, timeouts, and dependency cycles skip the agent without starting it. Cycles across either field are detected at parse time.
Wildcard waits
waitsFor: ["*"] waits for all other checks, excluding itself and other wildcard agents so those agents can run in parallel. requires: ["*"] also requires the waited-for checks to pass. You can combine a wildcard wait with a named requirement.
Timeouts
waitsForDiscoveryTimeout limits how long a named check may take to appear. waitsForTimeout limits the total wait for completion; discovery time is included in it. Both accept 1–60 minutes.
For named checks, discovery ends as soon as all names appear. For wildcard waits, the discovery window is a minimum delay on every run. Raising it to 10 minutes delays every wildcard run by at least 10 minutes; the check warns about this configuration.
Run and spend limits
Omitted or non-positive
maxRuns, maxBudgetPerRun, and maxBudgetPerPR mean no limit. Positive budgets below $0.00001 are raised to that amount; values above $100,000 are clamped, with a warning. maxBudgetPerRun is unsupported with code_object.
Limits are checked in this order: workspace balance and monthly limit, the workspace Check Run Agents per-PR limit, maxBudgetPerPR, then maxRuns. See Triggers and skips for which triggers bypass each one.
Budgets are best effort. Completed work is billed, and concurrent runs can overshoot limits. The workspace’s combined agent per-PR limit, balance, and monthly limit also apply. Raising an agent budget does not raise workspace limits.
Tools
Specifyingtools replaces the defaults, including comment-posting access. List every tool you want to retain.
Connect services in Settings → Connections. Tools without their required connection are silently disabled.