Setup
This guide gets kritika from a fresh installation to its first GitHub review.
You do not need a .kritika.yaml in your repositories. In place of the App,
declare:
- A bot for a Forgejo instance, as Git forges describes.
- A service account for a GitLab instance, as Git forges describes.
- A bot user for a Gitea instance, as Git forges describes.
Before you start
Section titled “Before you start”Have these ready:
- A Kubernetes cluster and Helm.
- Postgres with VectorChord and two database roles.
- An HTTPS address, such as
https://kritika.example.com, reachable by GitHub. - A model provider credential. The example below uses OpenRouter.
Install kritika in its own namespace. Keep the chart’s admission policy enabled. Configure its NetworkPolicy for your DNS and database. Where available, use a sandboxed runtime for runners, the Kubernetes Jobs that run reviews. See deployment security.
Register the GitHub App
Section titled “Register the GitHub App”In your GitHub account or organization’s Developer settings, create a GitHub App.
- Enable its webhook at
https://kritika.example.com/hooks/github. The final path segment must match the name underconfig.apps. - Set a random webhook secret.
- Give it the permissions below. Subscribe to the listed events.
- Generate a private key. Save the App’s client ID.
| Permission | Access |
|---|---|
| Contents | Read-only. If you want the bot to resolve finding threads, read and write. |
| Metadata | Read-only. |
| Pull requests | Read and write. |
| Issues | Read-only. Read and write for reactions on pull requests and conversation comments. |
| Commit statuses | Read and write. |
| Members (organization) | Read-only, only for GitHub sign-in that uses organization role mappings. |
Subscribe to Pull request, Pull request review comment, Pull request review thread, Issue comment, Push and Repository. Installation events arrive automatically.
Contents write access also permits pushing code, although kritika does not push. If you change permissions later, each installation must approve them.
Unless you intend to serve several accounts, allow installation only on your
account. Anyone can install a public App. kritika reviews only the accounts
listed in apps and ignores any other installation. An admin can uninstall
such an installation from the dashboard’s Connections section.
Deploy
Section titled “Deploy”Create a namespace for kritika. Provision these Secrets there with your usual secret management tool. Do not commit their values.
| Secret in this example | Keys |
|---|---|
kritika-postgres-credentials |
uri: owner database connection string. |
kritika-postgres-app |
uri: application database connection string. |
kritika-credentials |
ADMIN_PASSWORD, OPENROUTER_API_KEY, GITHUB_APP_PRIVATE_KEY, GITHUB_APP_WEBHOOK_SECRET. |
kritika-tls |
TLS certificate and key for your public hostname. |
The database guide explains the connection strings. Owner and application connections need direct or session-mode access. kritika does not support transaction-mode pooling.
Create Helm values like these. Replace the hostname, account, client ID and
vendor/large-model with your own values. Adapt the configuration of the
ingress, DNS and database network to your cluster.
config: webUrl: https://kritika.example.com auth: admin: password: { env: ADMIN_PASSWORD } apps: github: accounts: [your-org] clientId: Iv1.example privateKey: { env: GITHUB_APP_PRIVATE_KEY } webhookSecret: { env: GITHUB_APP_WEBHOOK_SECRET } providers: openrouter: type: openrouter apiKey: { env: OPENROUTER_API_KEY } review: model: openrouter/vendor/large-model
database: owner: existingSecret: kritika-postgres-credentials app: existingSecret: kritika-postgres-app
envFrom: - secretRef: name: kritika-credentials
ingress: enabled: true hosts: - host: kritika.example.com paths: [{ path: / }] tls: - hosts: [kritika.example.com] secretName: kritika-tlsThe chart’s NetworkPolicies, on by default, expect Postgres in the release
namespace, standard cluster DNS, and forges (such as GitHub) and models on
port 443. If yours differ, set
networkPolicy.postgres,
networkPolicy.dns and
networkPolicy.egressPorts. In networkPolicy.extraEgress, allow what
kritika serve reaches in the cluster, such as an S3 bucket or a model
server.
networkPolicy.type: auto renders Cilium’s or Calico’s own policies where
the cluster serves their API, and standard NetworkPolicies otherwise. Argo CD
passes the cluster’s APIs to helm template for it, but plain
helm template needs --api-versions or a type set.
Install the chart using your values file:
helm upgrade --install kritika oci://ghcr.io/home-operations/charts/kritika \ --namespace kritika --create-namespace --values my-values.yamlWhen config changes, the chart restarts pods. Changes to external Secrets or
ConfigMaps need a restart or a controller such as Reloader.
Install the App
Section titled “Install the App”Install the GitHub App on each account listed under config.apps.github.accounts.
Choose all repositories or selected repositories.
Installing the App grants access. Newly discovered repositories still need to be enabled in the dashboard.
Sign in
Section titled “Sign in”Open your public URL and sign in as admin with the password you supplied.
- Open All accounts → Accounts. Read the setup checklist.
- Select your account. Open Repositories.
- Enable a repository that you want reviewed.
You can add GitHub, Forgejo, Gitea, GitLab or OIDC sign-in later. Embedding is optional: it adds similar-code search but is not needed for the first review.
Check that it works
Section titled “Check that it works”Open a pull request in the enabled repository. Or, as a user with write
access, comment @<app-slug> review on an existing one. Look for a running
review in the dashboard, then a summary comment on GitHub.
If nothing happens, go through these questions:
- Is the repository enabled? Look at the account’s Repositories page.
- Was the webhook delivered? Open the GitHub App’s recent webhook deliveries.
- Did the job fail, or is it waiting? Open the dashboard’s Queue and expand its error.
| Webhook response | Meaning |
|---|---|
202 |
Accepted. The account and repository must still be enabled for reviews. |
204 |
Ping received. |
400, 413 |
Invalid or oversized delivery. |
401 |
Webhook secret missing or different from GitHub’s. |
404 |
App name in the URL is wrong. |
500 |
kritika failed to queue the delivery. |
For everyday use, see reviews and commands.
Without webhooks
Section titled “Without webhooks”Polling catches missed pull request updates every 10 minutes by default.
Set config.pollInterval to change the interval, or 0s to disable it.
When webhooks stop arriving, polls also catch up the code index.
The leader is the replica that runs the polls. A newly elected leader polls
at once, so a restart catches up on the pull requests opened, pushed to or
closed while kritika was down.
Reviews must wait for a poll, and mentions are never answered without webhooks. Shorter intervals use more GitHub API requests.