Skip to content

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.

Have these ready:

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.

In your GitHub account or organization’s Developer settings, create a GitHub App.

  1. Enable its webhook at https://kritika.example.com/hooks/github. The final path segment must match the name under config.apps.
  2. Set a random webhook secret.
  3. Give it the permissions below. Subscribe to the listed events.
  4. 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.

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-tls

The 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:

Terminal window
helm upgrade --install kritika oci://ghcr.io/home-operations/charts/kritika \
--namespace kritika --create-namespace --values my-values.yaml

When config changes, the chart restarts pods. Changes to external Secrets or ConfigMaps need a restart or a controller such as Reloader.

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.

Open your public URL and sign in as admin with the password you supplied.

  1. Open All accounts → Accounts. Read the setup checklist.
  2. Select your account. Open Repositories.
  3. 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.

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:

  1. Is the repository enabled? Look at the account’s Repositories page.
  2. Was the webhook delivered? Open the GitHub App’s recent webhook deliveries.
  3. 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.

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.