Repository settings
A repository works without any configuration file. If you want custom review
rules, ignored paths or trigger conditions, add .kritika.yaml at its root.
Start small:
# yaml-language-server: $schema=https://kritika.home-operations.com/kritika.schema.jsonignore: ["web/src/generated/**"]rules: - id: wrap-errors rule: 'Wrap errors with fmt.Errorf("<package>: %w", err).' paths: ["**/*.go"]kritika reads this file from the merge base, the shared ancestor of the pull request and its target branch. A pull request cannot change its own review rules. Merge a configuration change before expecting it to apply to later reviews. Indexing uses the configuration at the commit being indexed.
The file contains no credentials. Models must use a provider the admin configured. The JSON Schema provides editor completion and validation. For custom tools, see repository tools.
What it may set
Section titled “What it may set”Use only the configuration keys that you need. This table shows how each key interacts with the admin’s policy. Detailed examples follow the table.
| Key | What it sets | Against the admin’s value |
|---|---|---|
enabled |
false stops reviews, follow-ups (answers to questions in comments) and indexing |
can only turn the repository off |
review.model, review.fallback |
the models the review and follow-ups run on | replaces |
review.effort |
how hard they reason | replaces |
review.fixes |
true requires a suggested fix on every finding |
can only turn it on |
review.approve |
true approves a pull request the review allows, when only some |
replaces, and its when holds beside the admin’s |
review.diagram |
true draws the change’s flow in the summary |
replaces, either way |
confidence.* |
the score that judges a review, and the models that give it | replaces, risk can only be lowered, and when holds beside the admin’s |
trigger.include, trigger.exclude |
which pull requests are reviewed | judged beside the admin’s lists |
comments.inline |
false posts the summary alone, without inline comments |
replaces |
comments.summary, comments.finding |
templates for the summary and inline comments | replaces |
ignore |
paths the review and the index leave out | added |
rules |
checks the review makes | added after, and one under an admin’s id is dropped |
context |
files that explain the code | added after |
skills |
where the repository’s Agent Skills live, and when each is offered | paths replaces, and scope adds up |
tools |
the tools the reviews can run, beside the image’s commands | added, and one providing an image command replaces it |
review.agents |
agents that review beside the default pass (kritika’s own instructions), or replace it | specialists added, and one under an admin’s name takes only rules and skills. The others replace the admin’s |
kritika drops a value that the file cannot take, such as a model of an undeclared provider. The admin’s value applies for that field. A note in the review’s summary says which field kritika dropped and what it can be. The rest of the file still applies.
These keys are the admin’s alone: agent, trigger.limit,
review.incremental, review.cost, comments.dashboard,
confidence.instructions, confidence.floors and limits. A file that
names one of them, or any other unknown key, does not parse.
Models
Section titled “Models”review.model and review.fallback are each a <provider>/<model>, where
the provider is one that the instance or the repository’s account declares.
They are used for the review and for follow-ups. A model of any other
provider is dropped, and the account’s limits bound what a choice can cost.
review.model replaces the admin’s model and the admin’s agents that
replace the default pass.
The file can write its own such agents. When a review’s model fails, the
review goes on with the fallback, on the same provider or another. A
follow-up does the same.
review.effort sets how hard the review model reasons, and
confidence.effort sets how hard the scorer, the model that scores a
review, reasons. Each covers its fallback too. The value is one of none,
minimal, low, medium, high, xhigh or max
(effort). Each setting replaces the admin’s. "" restores the provider’s default, and a value
that is not a level is dropped.
Approvals
Section titled “Approvals”review.approve: true has kritika approve a pull request that its review
allows. That is one with no findings at P0 or P1, or, with a confidence
score, one whose score and risk allow it. The setting replaces the admin’s
in either direction, so a repository can turn it on where the instance
leaves it off (approvals).
A block with when conditions, like a rule’s, approves only a
pull request that one of them holds for:
review: approve: when: - name: small bumps expr: pr.bot && pr.labels.exists(l, l.name in ["type/patch", "type/minor", "type/digest"])The block turns approval on, and its conditions hold beside the admin’s. A
pull request must pass both, so the file cannot approve what the admin’s
conditions keep out. approve: true also keeps the admin’s conditions.
kritika never approves a pull request that changes .kritika.yaml or
another file that configures kritika. No
condition changes this.
Flow diagrams
Section titled “Flow diagrams”With review.diagram: true, the summary draws the flow that the change adds
or alters: a request path, a data flow or a state machine. It is a Mermaid
flowchart or sequence diagram that the forge renders, and its nodes are
plain-language steps rather than function names. The diagram is off unless
set, since it costs output tokens on every review. The setting replaces the
admin’s in either direction.
- The model leaves it out when the change has no such flow, as for a version bump or a documentation change.
- kritika keeps only a flowchart, graph or sequence diagram under 4 KiB.
- A re-review of the commits since the last review is shown that review’s diagram. It returns the diagram as it is, redrawn where the new commits alter the flow, or empty once the flow is gone. When it answers with no diagram at all, kritika keeps the last one.
Confidence
Section titled “Confidence”confidence.model, confidence.fallback, confidence.effort,
confidence.threshold and confidence.gate replace the admin’s. The
threshold and the gate do so in either direction. The models are held
to the same providers as review.model (models). The fallback
takes the scorer’s call when the confidence model fails. confidence.risk
can only lower the admin’s, and a higher one is dropped.
confidence.gate can be a block of when conditions, as review.approve
can. It then gates only a pull request that one of them holds for. It
replaces the admin’s, conditions and all.
confidence.when lists conditions, as a rule’s when does. One of them
must hold for a pull request to be scored, and the admin’s conditions apply
as well. A pull request that the file’s conditions leave unscored is
reviewed without a score. Where the admin asks for a score, that pull
request is also not approved. So the file cannot lift the admin’s risk
policy by narrowing scoring.
confidence.instructions and confidence.floors are the admin’s alone
(confidence and approvals).
Trigger conditions
Section titled “Trigger conditions”trigger.include and trigger.exclude are conditions on the pull
request. Each condition is an expr, paths globs (path patterns), or
both, with an optional name. paths globs hold when a changed path
matches one. With both, both must hold. A pull request is reviewed when
no exclude holds and either one include holds or there are none.
- The lists are judged beside the admin’s own, and a pull request must pass both. A condition with the same name as one of the admin’s is dropped, and the review’s summary says so.
- kritika compiles each expression and smoke-tests it against a sample pull request when it parses the file. So kritika rejects a broken expression, rather than letting it silently skip every review.
- A condition on the pull request alone is decided before any runner, the
pod that runs a review, starts. One with
pathsorpr.linesis decided once the pull request is fetched, before any model is called. When the lists keep a review out, its commit status names the exclusion that held, if that exclusion has a name.
See the recipes.
Ignored paths
Section titled “Ignored paths”ignore adds path globs to the admin’s own ignore list, for reviews and
indexing alike. A pull request is skipped when every changed path is
ignored, whether by these globs, the admin’s globs or kritika’s defaults.
The defaults cover vendored trees, lockfiles, generated and minified code,
source maps and logs.
rules are checks the review makes, added after the admin’s:
| Key | What |
|---|---|
id |
lowercase letters, digits and hyphens, at most 64 characters. Findings cite the rule by it |
rule |
the check itself, at most 2000 characters |
file |
instead of rule, a file read from the same merge-base tree whose content is the check |
paths |
optional globs. The rule applies only when a changed path matches one. So checks for one part of the repository do not spend the room on changes elsewhere |
when |
optional conditions as trigger.include takes them, each an expr with an optional name. The rule applies only to a pull request that one of them holds for, such as pr.headRef.startsWith("renovate/") for Renovate’s pull requests |
- A
whencondition is compiled and smoke-tested like a trigger condition, and one that fails to evaluate does not hold. - A rule whose
idan admin’s rule has is dropped, and the review’s summary says so. - The rules a change matches are listed by id in the system prompt, and in a follow-up’s, within the limits. A file rule goes under a heading of its own. A finding lists the ids of the rules that it enforces. The list keeps only the ones that its review was given.
- A finding that cites a rule also quotes the passage of the rule that the change breaks. The finding’s inline comment shows this quote. The quote must be in one of the rules that the finding cites. The comparison ignores markdown, case and spacing. The quote must also be at least 12 characters of the rule, unless the rule is shorter. A finding that cites no rule carries no quote.
- If a finding in a submission cites a rule that it does not quote, kritika sends the submission back to the review to correct. It does the same for a malformed one. kritika names every such finding. It sends the submission back twice at most. If a review does not correct those findings by then, it keeps the rest of its submission and loses those findings. Those findings never post.
Rule files
Section titled “Rule files”Each markdown file under .agents/rules and .claude/rules, at any
depth, is a file rule, with nothing to configure. These are the
directories where coding agents keep path-scoped conventions. kritika
reads them from the merge base, as it does rules, so a pull request
cannot add or rewrite a rule file to steer its own review.
---paths: - "**/*.rs"---
Never discard an error with a bare `let _ =`.- The rule’s id is the file’s path below the directory, without
.md, lowercased, with every run of other characters than letters and digits a hyphen. So.claude/rules/backend/API.mdisbackend-api. Findings cite it by that id. - The file’s
pathsfrontmatter limits the rule to changes that touch a matching path, as a rule’spathsdoes.pathsis a list of globs or one comma-separated string, relative to the repository root. A file without it applies to every change. kritika reads no other frontmatter key, and leaves the frontmatter out of the rule. Frontmatter that does not parse is dropped, and the file then applies to every change. An invalid glob matches nothing, and the file’s other globs still apply. - A configured rule that names the file as its
filetakes its place. A file whose id a configured rule has, admin’s or the repository’s, is left out, with a summary note. So is a file whose id an earlier file has..agents/rulesis read before.claude/rules. - Rule files come after the configured rules and share their 32 KiB of
rule files. Among them, the ones with
pathscome first, then the ones that apply to every change. So a long file that applies everywhere does not take the room of the rules narrowed to the change. A file longer than the 32 KiB on its own can never fit, and is left out with a note that says to split it. When the rules a change matches do not fit, the summary note names the ones left out. - The default reviewer and its follow-ups are given rule files. An agent
with its own instructions keeps its own rules alone, as it does for
rules. - A symlinked file is passed over: kritika reads files from the merge base, where a symlink holds a path rather than the rule.
- No key configures rule files. A repository without these directories discovers none. To keep a file out of reviews, move it out of them, or write a rule under its id, which takes its place.
Context
Section titled “Context”context lists files that explain the code, added after the admin’s. Each
entry is a path with a description and optional paths globs. kritika
points the review or follow-up at each file, so that it can read the file
with its own tools, from the pull request’s head, its latest commit. A
pull request can change or delete that content.
These are optional references, not instructions. Requirements that must
survive changes in the pull request belong in rules. A file with
paths applies only when a changed path matches one of them.
If the admin already lists the same path, the admin’s description and scope win. kritika drops the repository’s entry, with a summary note. kritika does not make sure that paths exist when it offers them. A missing file produces a tool error if the reviewer tries to read it.
Reference pointers reserve up to a quarter of the user prompt budget. kritika shortens an oversized list, with a summary note. The prompt also says when kritika omitted pointers. This includes the prompts of follow-ups.
Skills
Section titled “Skills”skills are the Agent Skills the repository
keeps for its reviews. A skill is a folder that holds a SKILL.md, with
any files the skill needs beside it. The SKILL.md has YAML frontmatter,
then instructions. The frontmatter has a name and a description. The
name uses lowercase letters, digits and hyphens, at most 64 characters,
and is the folder’s name when unset. Each folder directly under
.agents/skills and .claude/skills that holds a SKILL.md is a skill,
with nothing to configure.
| Key | What |
|---|---|
skills.paths |
the directories whose folders are skills. It replaces the admin’s. paths: [] looks nowhere, which turns skills off for the repository |
skills.scope.<name> |
narrows when the skill of that name is offered. It is added to the admin’s scopes, and a skill named in both takes this file’s |
skills.scope.<name>: its paths are globs, and a changed path must match
one of them. Its when lists conditions as a rule’s does, and one of them
must hold. With both, both must hold.
When a scope has paths or when, a review that the skill applies to gets
the skill’s instructions in the system prompt. The review gets these rather
than the skill’s name to read. load: false offers the skill by name
instead. With load: true, a skill whose scope has neither paths nor
when is given whole to every review.
- kritika reads skills from the merge base, as it does this file and the rules. So a pull request cannot add or rewrite a skill to steer its own review.
- A skill is offered by name, or given whole. The system prompt lists each
skill’s name and description. When a skill fits the pull request, the
review reads its instructions, or a file in its folder, with its
load_skilltool. The review reads these from the merge base too. - A skill whose scope has
pathsorwhenskips that step, since the scope already decides where it applies. So does a skill whose scope saysload: true. When such a skill’spathsandwhenhold, the review starts with its instructions in the system prompt.load_skillstill serves the files in its folder. Some scopes narrow without deciding, such as every Go change for a reference skill that only sometimes helps there. Such a scope saysload: falseto keep the skill offered by name. - A skill can be left out, and this is not fatal. kritika leaves out and
notes a skill past a limit, rather than failing the review. It
does the same for a skill whose
SKILL.mdhas no frontmatter, no description or a name that another skill has. - A skill grants no tools. kritika ignores
allowed-toolsand every other frontmatter key. A skill guides a review but grants it no tool or command. The review skips a step that needs a tool or command that it was not given. - The summary’s collapsed Review context block reports skills. It
counts the skills that the review was offered and names the ones that it
read. For example, it shows
1/2 skillson the block’s line andSkills read: review-renovate-prinside it. Each read also shows in the review’s transcript, and a skill given whole counts as read. The block counts commands offered to a review through the run tool the same way, beside the skills, such as1/2 commandsandCommands run: helm. - An agent with the review’s tools and commands answers follow-ups, under
the same
agentlimits, in a runner of its own. That agent is offered no skills. - A worked example is Sentry’s
gha-security-reviewskill. It reviews GitHub Actions workflows with an explicit threat model and a table of safe patterns not to flag. It requires a concrete exploit for every finding. Itsreferences/load throughload_skill, as any file in the folder does. - Scope that skill with
skills.scope.gha-security-review.paths: [".github/workflows/**"]. Make sure that its exceptions fit your own policy. It leaves first-party actions on version tags alone. A repository that pins every action to a digest does not leave them alone.
Rules, context and skills compared:
| In the prompt | Cited by findings | |
|---|---|---|
| A rule | whole, wherever it applies | yes, by id |
A context file |
a pointer, with the configuration’s description | no |
| A skill | its own description, until the review reads it, or whole, when its scope loads it | no |
Agents
Section titled “Agents”Every review has a default pass: kritika’s own instructions, on
review.model, with the repository’s rules and skills.
review.agents is a list of agents beside it, each by its name:
review: model: anthropic/claude-sonnet-5-5 # the default pass fallback: anthropic/claude-haiku-5-5 effort: medium agents: - name: security # limited to categories: runs beside the others model: anthropic/claude-opus-5-5 categories: [security] instructions: Review as an application security engineer. when: [{ name: auth, paths: ["**/auth/**", ".github/workflows/**"] }] - name: deep # every category: replaces the default pass model: anthropic/claude-opus-5-5 effort: high when: - { name: migrations, paths: ["db/migrations/**"] } - { name: large, expr: pr.lines > 800 }An agent with categories is a specialist. It reviews the change, or the
files its paths cover, for those categories alone. It runs as an agent of
its own beside the default pass, when one of its when conditions holds, or
always if it has none.
An agent without categories replaces the default pass when its conditions
hold. The first such agent whose conditions hold picks the review’s model,
as agents that replace the default
pass describes. It takes
only name, model, fallback, effort, when and enabled.
A specialist takes:
| Key | What |
|---|---|
name |
lowercase letters, digits and hyphens, at most 64 characters, not default. The comments credit a finding to it |
categories |
the only finding categories it can report. Its schema and its submission check refuse the rest |
instructions |
what it reviews for, at most 8000 characters, added after kritika’s own instructions |
file |
instead of instructions, a file read from the merge base whose content they are. kritika uses the first 32 KiB |
model, fallback, effort |
as review.*, for this agent. Where unset, the default pass’s, as the agents picked it |
paths |
the changed files it reads, every one when unset. It does not review a pull request that changes none of them |
when |
conditions as a trigger’s, {name, expr} or {name, paths} with pr.lines usable: it runs only on a pull request one of them holds for |
rules |
its checks, in place of the repository’s, which are the default pass’s |
skills.scope |
skill scopes laid over the repository’s for this agent, so a skill can be given whole to it alone |
agent |
steps, tokens and timeout (at least 1s and at most 2h35m) for its agent, or each of its parts. They can lower the repository’s agent bounds and never raise them |
enabled |
false turns it off |
- kritika merges the agents’ answers into one review: one summary comment,
one commit status and one confidence score. Each inline finding names the
agent that raised it, as in
P1 · Open redirect · security · security. The summary’s Review context block lists the agents that ran. A review by the default pass alone names no agent, in that block or on its findings. - Duplicates merge. When two agents raise the same thing (one path, overlapping lines, the same category or title), kritika posts one comment. That comment is the more severe finding, and it credits both agents.
- kritika splits a large diff by agent: into parts within each agent. It sizes and budgets the run for every agent’s parts. An agent whose parts did not all submit leaves the review incomplete. Its findings are posted, and the summary names the agent. A retry of the same job reuses the parts that did submit.
- kritika judges agents over the whole pull request. It decides which agents run, and on which model, from the whole change before it calls any model. So a pull request keeps its agents from push to push, and its author cannot talk one away.
- Incremental reviews work per agent. A re-review builds on the last review
only for the agents that the last review ran. An agent that the last
review did not run, for example one whose
whenfirst holds on a later push, reviews its files whole. None of that agent’s findings is held back. - A reply or mention in a finding’s thread is a follow-up. The specialist that raised the finding answers it, with its instructions, rules and model, while that specialist is on. Otherwise the default pass answers.
- Agents also run on demand.
@<bot> review <name>runs that specialist alone, whatever itspathsandwhen. It carries the other agents’ findings on unchecked.@<bot> review defaultruns the default pass alone. For an agent without categories,@<bot> review <name>runs the default pass on that agent’s model. A name that matches no agent that is on runs every agent that applies, with a note. - From this file, a specialist among the admin’s agents can only gain
rules and skill scopes. The rules must have ids of their own, and the
scopes must be for skills that it does not scope. kritika drops anything
else written for it, with a note. The file’s agents without categories
replace the admin’s whole, as its
review.modeldoes. They do so even when every one of them is off. - kritika drops the file’s agents without categories whole when one of them names a model of a provider that the account cannot use. It also drops them whole when, together with the admin’s specialists, they pass the limit on agents.
- kritika drops an agent named
default, with a note, and the rest of the file applies. The same is true of an agent under the name of an admin’s agent of the other kind: a specialist where the admin’s agent replaces the default pass, or the other way round. - Agents share tools. A specialist runs the repository’s tools and commands, as the default pass does. There is no per-agent tool list.
- A review holds model slots. It holds a slot of the provider’s
concurrencyon the model of each specialist it runs. It does the same on the default pass’s model. It waits for those slots as it waits for the default pass’s. A split review runs each specialist’s parts in its own model’s slots, as many at once as are free, and specialists on one model share its slots.
Each specialist spends tokens of its own: with two, a review costs about three times as much. The dashboard’s review timeline shows each part’s agent and cost, with a total by agent.
Agent files
Section titled “Agent files”Reviews and follow-up answers do not automatically load AGENTS.md or
CLAUDE.md. To offer one as reference material, list it under context
in .kritika.yaml:
context: - path: AGENTS.md description: Repository architecture and coding conventions - path: web/AGENTS.md description: Frontend architecture and conventions paths: ["web/**"]These follow the context semantics, and this includes reading
from the pull request’s head. You must list directory-specific files
explicitly. paths limits when each reference is offered. Name the file
that contains the actual text. kritika does not automatically follow
@AGENTS.md imports and symlinks, and tool paths are relative to the
repository root.
Context is reference material, not instructions. Put requirements that every applicable review must enforce into rules. Put review procedures into skills. A rule can name a file that contains review requirements. Keep coding-agent workflows, such as committing and opening pull requests, out of that file.
Skills are available to reviews only, not follow-up answers. Put
requirements shared by both in rules. An agent file that is not listed is
not offered as context, and no review warns that it is missing. The
files under .agents/rules and .claude/rules are the exception: they
are rule files, with nothing to list.
Comment templates
Section titled “Comment templates”comments.summary and comments.finding are paths to Go
text/template templates that replace
kritika’s built-in summary and inline comment templates. Where the admin
set a template, an empty path restores the built-in one.
- Templates can use the sprout
helpers that tuppr and chaski expose: std, strings, conversion, encoding,
numeric, slices, maps, regex, time, semver and reflect. Templates cannot
use env, filesystem, network, random, uniqueid, checksum or crypto, and
cannot use
setorunset. - kritika refuses the actions
template,defineandblock. So a template cannot read any file or call any other template. - Rendering has bounds (loop iterations, bytes per function call, output size, a deadline). So a template cannot hang or exhaust memory. A template that exceeds a bound falls back to the default, with a note in the summary.
The summary template’s dot is the review:
| Field | What |
|---|---|
.Number |
the pull request’s number |
.HeadSHA, .HeadURL |
the head commit, and a link to it |
.HeadSubject |
the head commit’s subject line, cut to 40 characters and escaped for Markdown |
.Reviews |
how many reviews of the pull request this one makes |
.Model |
the review model |
.Effort |
the effort it reasoned at, “” for the provider’s default |
.Route |
the agent that replaced the default pass and the condition that held, escaped for Markdown, “” for the default |
.Cost |
what the pull request’s reviews have cost, “” unless the admin’s review.cost is on |
.AuthorIsBot |
whether a bot opened the pull request |
.Result.Summary.Headline, .Result.Summary.Take, .Result.Summary.Praise |
the review’s headline, its take, and what it found good |
.Result.Summary.Diagram |
Mermaid source for the flow the change adds or alters, “” unless review.diagram is on and the change has one |
.Result.Findings |
the findings, each as the inline template sees one. An earlier finding that an incremental re-review carried on unchecked has .CarriedFrom: the head it was last reported at, whose lines its .URL links |
.Counts.P0, .Counts.P1, .Counts.P2, .Counts.Total |
the findings by severity and all of them, those outside the diff and those carried on unchecked included |
.Unanchored |
the findings on lines the diff does not show |
.HeldBack |
an incremental re-review’s new findings more than 3 lines from what changed since the last review, not counted |
.Notes |
the review’s notes |
.Incremental, .PriorHeadSHA, .PriorHeadURL |
whether the review covered only what changed since the last one, and that review’s head |
.Prior |
the last review’s findings this review listed as resolved, with .Resolved and .ThreadResolved or .ThreadOpen, how its thread stands on the forge, then those dismissed, with .Dismissed and .DismissReason |
.FixedPrior, .OpenPrior |
the findings of .Prior listed as resolved, the ones the built-in template lists, and those of them whose thread stands open |
.Sources |
links to what the review’s commands fetched |
.Agents, .NamedAgents |
the agents the review ran, in order, and whether a specialist ran, alone or beside the default pass |
.Skills, .Commands |
the repository’s skills and the run tool’s commands the review was offered |
.Overlaps, .NamedOverlaps, .MoreOverlaps |
the repository’s other open pull requests that change a file this one changes, most shared files first. Then the first 5, and how many that leaves out |
.Incomplete |
why the head was not fully reviewed, “” otherwise |
.Confidence |
nil unless the review was scored |
.Approval |
nil unless review.approve is on: .Approved and .Reason, “” when a confidence score approved it |
.Clean |
whether the review scored 5/5, found nothing, held nothing back, has no notes and is approved or not asked to approve. The built-in template then states it in one line and moves the scorer’s reason into the review context |
.WebURL, .PullURL |
the dashboard’s origin, which serves the built-in template’s severity badges, and the pull request’s page on it, where its View and Re-run badges point. Both “” when the admin’s comments.dashboard is off |
.Skills and .Commands each have:
.Names: every one offered.Used: the ones the review read or ran.Named:.Usedsorted and cut to the first 10.More: how many.Namedleaves out
Each of .Overlaps has:
.Numberand.URL: the pull request, its URL “” when unknown.Shared: the paths both change, sorted.NamedShared,.Spansand.MoreShared: the first 3, the same as Markdown code spans, and how many that leaves out.Stale: whether its head moved since the review whose paths these are
.Confidence has:
.Score,.Threshold,.Passedand.Risk.Reason: the scorer’s own.Explanation: the reason, then how a floor held the risk when one did.Ratedand.Held: the scorer’s rating and the path that held it, “” when none did.Model
The inline template’s dot is one finding, with the dashboard’s origin beside it:
| Field | What |
|---|---|
.Path, .Line, .EndLine |
where it is |
.Severity, .Category |
how much it matters, and what kind of problem it is. .Severity.Label is its badge text, P0 to P2, and .Severity.Badge .WebURL is the badge image, or the label in bold without a dashboard |
.WebURL |
the dashboard’s origin, “” when the admin’s comments.dashboard is off |
.Title, .Explanation |
what it is |
.Agents, .AgentNames |
the agents that raised it, none for the default pass alone, and their names joined for a comment, “” for the default pass alone |
.SuggestedFix |
the fix, in prose |
.Replacement |
the lines that replace the finding’s, for a one-click suggestion |
.AgentPrompt |
a prompt a coding agent can apply the fix from |
.AgentPromptFence |
a code fence longer than any in the prompt |
.Rules |
the ids of the rules it enforces |
.Quote, .BlockQuote |
the passage of a cited rule it enforces, “” when it cites none, and that passage as a Markdown block quote |
.URL |
a link to the lines at the head commit |
.ThreadURL |
a link to its inline comment thread, once one is posted |
Repository tools
Section titled “Repository tools”A repository adds tools for its own reviews under tools. kritika reads
the key from the merge base like the rest of the file. So a pull request
that changes it uses the previously merged version for its own review.
Each entry is a package of the
aqua registry, named aqua:
and the package’s name, with the tag of the release to run. A package’s
name is its repository’s owner and name, with a path for one of several
tools a repository releases, such as aqua:apple/pkl-go/pkl-gen-go. The
commands a tool offers are the ones the registry names for it.
The repository’s tools add to the image’s commands: curl, find, gh,
grep and jq. A tool that provides one of those commands replaces it,
gh excepted, while the others remain available.
tools: aqua:home-operations/flate: v0.6.5 aqua:BurntSushi/ripgrep: 15.1.0 aqua:kubernetes-sigs/kustomize: kustomize/v5.8.3Give each tool its release’s tag as the release names it, a v or any
other prefix included. A version with no digit in it, such as latest,
fails the file: a download URL that takes it reads as whatever is newest.
A tag the release does not have fails the install, which names it.
A tool installs at the version given, on the first call that needs it. This can take a moment. A failed install fails that tool call without stopping the review.
The runner reads the registry from kritika’s gateway. The gateway keeps
aqua-registry’s main branch, unless the admin’s aquaRegistryUrl names
another source. The gateway asks for the registry again every hour
(how kritika runs). A package added to
the registry, or a definition fixed in it, is offered within that hour.
This takes no change to this file or to kritika.
Release hosts need the admin’s egress.allow permission
(runner tools). For a tool with GitHub artifact
attestations, the host where GitHub keeps their bundles needs it too. Once
the admin gives the gateway a download cache, later runs reuse a checked
download (the gateway’s cache).
No lock is committed. Before a download, the runner fetches what the download must match. That is the digest that GitHub keeps of a release’s asset, else the checksum file that the registry names for the package. The fetch of the digest also makes sure that the version is one of the release’s tags. A tool with neither is not installed.
The runner makes sure that the download matches before it unpacks anything of it. An install only downloads and unpacks.
Where the registry declares a signature of the download or of its checksum file, the runner makes sure that the signature is valid too. The signature can be a cosign bundle, a GitHub artifact attestation, SLSA provenance in a Sigstore bundle, or a minisign signature. A checksum file with a signature is read in place of GitHub’s digest, as aqua reads it. A signature that fails verification fails the install.
The runner skips signature verification for the forms below. The runner’s log says so, and the tool installs on its checksum alone.
- A cosign signature and certificate apart from a bundle
- A key-signed signature
- Provenance outside a Sigstore bundle
- An attestation by GitHub’s own Sigstore instance
These are not offered, and the review’s summary says why:
- A package that the registry does not have
- A package that builds from source (
go_install,go_build,cargo) or takes a repository’s files rather than a release’s (github_content,github_archive) - A package with no download for the version or the runner’s platform
- A package whose download is packed in a way that the runner does not
unpack, such as
dmg,pkg,raror7z - A package whose commands the registry lays out as links
- A command that another tool already offers, with the tools taken in the order of their names
Updating tools with Renovate
Section titled “Updating tools with Renovate”A custom regex manager offers the updates. On the line above each tool, annotate the datasource and the GitHub repository for Renovate to follow:
tools: # renovate: datasource=github-releases depName=home-operations/flate aqua:home-operations/flate: v0.7.3Then give Renovate the manager. It takes the tag as the version, so the
v stays:
{ "customManagers": [ { "customType": "regex", "managerFilePatterns": ["/^\\.kritika\\.yaml$/"], "matchStrings": [ "# renovate: datasource=(?<datasource>\\S+) depName=(?<depName>\\S+)(?: versioning=(?<versioning>\\S+))?\\n\\s*\"?aqua:[^\"\\s]+\"?:[ \\t]*\"?(?<currentValue>[^\"\\s]+)\"?" ], "versioningTemplate": "{{#if versioning}}{{{versioning}}}{{else}}semver{{/if}}" } ]}A tag with a prefix other than v, such as kustomize/v5.8.3, needs a
versioning= of its own on the annotation.
Include and exclude recipes
Section titled “Include and exclude recipes”The expr of a trigger.include or trigger.exclude condition, like a
rule’s when conditions, is a CEL expression over
pr:
| Field | What |
|---|---|
number, title, body, author, url |
the pull request |
state, open, merged, draft, fork |
its state |
bot |
whether a bot opened it, as the forge marks one, or a Forgejo or Gitea connection lists its login under bots |
headRef, headSha, baseRef |
its branches and head commit |
createdAt |
when it was opened |
labels |
its labels, each with a name and a color |
event |
what started the review (below) |
lines |
the lines its diff adds and removes, paths the ignore globs match left out. Trigger conditions and a review.agents entry’s when only, not a rule’s |
event |
What started the review |
|---|---|
opened, reopened, ready_for_review |
the pull request opened, reopened or became ready |
synchronize |
a push |
poll |
a push kritika found without its webhook |
labeled, unlabeled |
a label added or removed |
manual |
a re-run from the dashboard, or @<bot> review |
A condition’s paths are globs, as on a rule: it holds when a changed
path matches one of them. With an expr too, both must hold. An
exclusion with paths skips a pull request that touches the paths at
all. ignore leaves the paths out of the review, and skips only a pull
request that changes nothing else.
A label change starts a review only for a head that has none yet: one that
the lists kept out, or one whose review failed. So removing skip-review,
or adding the label a condition asks for, gets the pull request reviewed
without waiting for its next push.
Some conditions, each under trigger:
| To | Write |
|---|---|
| Skip drafts | exclude: [{ expr: pr.draft }] |
Skip anything labeled skip-review |
exclude: [{ name: skip-label, expr: 'pr.labels.exists(l, l.name == "skip-review")' }] |
| Skip Renovate’s pull requests | exclude: [{ expr: pr.author.startsWith("renovate") }] |
| Skip pull requests from forks | exclude: [{ name: forks, expr: pr.fork }] |
| Skip when the description asks to | exclude: [{ expr: 'pr.body.contains("[skip-review]")' }] |
Review only pull requests into main |
include: [{ expr: pr.baseRef == "main" }] |
| Review when a pull request opens or is re-run, not on every push | include: [{ expr: 'pr.event in ["opened", "reopened", "ready_for_review", "manual"]' }] |
Review only pull requests that touch src/** |
include: [{ name: source, paths: ["src/**"] }] |
| Skip pull requests over 2000 changed lines | exclude: [{ name: too-large, expr: pr.lines > 2000 }] |
Never review automatically a pull request touching db/migrations/** |
exclude: [{ name: migrations, paths: ["db/migrations/**"] }] |
The last holds only for automatic reviews in the admin’s configuration: a
review someone asks for still runs. In .kritika.yaml the exclusion holds
for that one too.
A named exclusion shows in the skipped review’s commit status:
kritika: skipped (filtered: skip-label).
Limits
Section titled “Limits”A configuration file that fails to parse is ignored as a whole, and noted rather than failing the review. The configuration and prompt limits below produce summary notes when content is omitted:
| What | Limit |
|---|---|
.kritika.yaml, each rule file and comment template |
256 KiB |
| those configuration files together | 1 MiB |
| the rules in the prompt | 16 KiB of rule text, 32 KiB of rule files |
| rule files discovered | 100 read |
| skills | 50 read |
| a skill’s description | 1024 characters |
| the skills’ names and descriptions in the prompt | 4 KiB |
| the skills given whole in the prompt | 32 KiB, and one past it is offered by name |
| agents | 8, the admin’s and the file’s together |
| an agent’s instructions | 8000 characters, or 32 KiB of its file |
Context file contents are read on demand by read_file, outside the
configuration-file limits above. Each read is capped at agent.output
(32 KiB by default), and blobs over 1 MiB are refused. A cut or refusal
is reported in the tool response, not as a summary note. Line ranges let
the reviewer read more of a file within the blob limit.