Skip to content

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.json
ignore: ["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.

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.

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.

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.

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.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.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 paths or pr.lines is 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.

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 when condition is compiled and smoke-tested like a trigger condition, and one that fails to evaluate does not hold.
  • A rule whose id an 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.

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.md is backend-api. Findings cite it by that id.
  • The file’s paths frontmatter limits the rule to changes that touch a matching path, as a rule’s paths does. paths is 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 file takes 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/rules is read before .claude/rules.
  • Rule files come after the configured rules and share their 32 KiB of rule files. Among them, the ones with paths come 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 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 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_skill tool. The review reads these from the merge base too.
  • A skill whose scope has paths or when skips that step, since the scope already decides where it applies. So does a skill whose scope says load: true. When such a skill’s paths and when hold, the review starts with its instructions in the system prompt. load_skill still 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 says load: false to 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.md has no frontmatter, no description or a name that another skill has.
  • A skill grants no tools. kritika ignores allowed-tools and 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 skills on the block’s line and Skills read: review-renovate-pr inside 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 as 1/2 commands and Commands run: helm.
  • An agent with the review’s tools and commands answers follow-ups, under the same agent limits, in a runner of its own. That agent is offered no skills.
  • A worked example is Sentry’s gha-security-review skill. 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. Its references/ load through load_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

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 when first 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 its paths and when. It carries the other agents’ findings on unchecked. @<bot> review default runs 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.model does. 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 concurrency on 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.

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.

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 set or unset.
  • kritika refuses the actions template, define and block. 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: .Used sorted and cut to the first 10
  • .More: how many .Named leaves out

Each of .Overlaps has:

  • .Number and .URL: the pull request, its URL “” when unknown
  • .Shared: the paths both change, sorted
  • .NamedShared, .Spans and .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, .Passed and .Risk
  • .Reason: the scorer’s own
  • .Explanation: the reason, then how a floor held the risk when one did
  • .Rated and .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

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.3

Give 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, rar or 7z
  • 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

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.3

Then 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.

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).

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.