Octopus (Self-Hosted PR Review)
Octopus is a self-hosted AI code-review tool. It receives GitHub pull-request webhooks, indexes the repository into a vector store, reviews diffs with an LLM, and posts inline severity-rated comments.
This cluster runs a fork (seanb4t/octopus) that carries a
small set of env-gated patches on the upstream v1.3.1 release (see
Fork state).
Every LLM call and every embedding call goes to the LiteLLM Service in the cluster. Octopus uses
three LiteLLM lanes: octopus-review, octopus-utility and octopus-embed. Each lane reaches
only OpenRouter providers with zero data retention (ZDR, a provider that stores no request
content). LiteLLM, The ZDR key describes how OpenRouter
enforces that rule.
Architecture
Section titled “Architecture”| Piece | Detail |
|---|---|
| Image | ghcr.io/seanb4t/octopus (web) and ghcr.io/seanb4t/octopus-migrate, multi-arch, digest-pinned from the fork branch upgrade/v1.3.1-analysis |
| Web | One Deployment in the octopus namespace with the in-process pg-boss review worker (ENABLE_REVIEW_WORKERS=true) and dnsConfig ndots:1 (alpine/musl and the fzymgc.house search-domain trap) |
| Schema | The octopus-migrate initContainer runs prisma migrate deploy on every start. See Schema migrations |
| Vector store | Dedicated qdrant-octopus on its own longhorn-encrypted PVC. code_chunks is 1024-dimensional (OCTOPUS_EMBED_DIM=1024, the octopus-embed lane). Telemetry upload is off (QDRANT__TELEMETRY_DISABLED=true) |
| Database | Dedicated octopus database on the main CNPG cluster (pg-boss queue and app data) |
| LLM and embeddings | OPENAI_BASE_URL=http://litellm.litellm.svc.cluster.local:4000/v1. LiteLLM validates the octopus virtual key (OPENAI_API_KEY, Vault cluster/litellm-keys/octopus, property api_key). The internal CA is trusted through NODE_EXTRA_CA_CERTS=/etc/ssl/fzymgc/fullchain.crt, mounted from the fzymgc-ica1-ca ConfigMap. Node needs the root, and ca.crt alone fails with UNABLE_TO_GET_ISSUER_CERT |
| Auth (UI) | Keycloak SSO through Better Auth genericOAuth, plus magic link. The provider id stays authentik so that existing linked accounts keep working (see tf/keycloak/octopus.tf). Built-in social logins are hidden (DISABLE_SOCIAL_LOGINS=true). OIDC_PROVIDER_NAME labels the login button. ADMIN_EMAILS gates platform admin and must match the Keycloak-surfaced email |
| Webhook (public) | octopus-wh.fzymgc.net/api/github/webhook through the Cloudflare tunnel webhook_services entry in tf/cloudflare/variables.tf, HMAC-verified with github_webhook_secret |
| Admin UI (internal) | octopus.fzymgc.house, a Traefik IngressRoute on the Lab VIP, internal names only |
| GitOps | ArgoCD Application octopus (argocd/cluster-app/templates/octopus.yaml) reads argocd/app-configs/octopus/ |
Review flow
Section titled “Review flow”- GitHub sends a
pull_requestwebhook tooctopus-wh.fzymgc.net/api/github/webhook(HMAC-verified). - Octopus enqueues a pg-boss
process-reviewjob. The in-process worker retrieves relevantcode_chunks(dense plus sparse RRF) from Qdrant. - Octopus sends the review call to LiteLLM with the model name
octopus-review. That name is a LiteLLM lane. The lane sets the model, the reasoning effort and the provider rule, and LiteLLM sends the call to OpenRouter. - Findings post as inline comments with severity. Findings at or above the org’s
checkFailureThreshold(defaultcritical) submit the review asREQUEST_CHANGES. Otherwise the review is aCOMMENT. - A push that leaves the diff against the base branch unchanged, such as a rebase onto a moved
main, reuses the last completed attempt: no model call, no new inline comment, one review that names the earlier commit, and the check run of that attempt. A comment@octopus reviewalways runs the model.
Repository indexing (Create Index or Sync) embeds in batches of EMBEDDING_BATCH_ITEMS (64, see
Embedding pipeline limits) through LiteLLM’s octopus-embed lane
(bge-m3, 1024 dimensions).
Octopus uses no Anthropic model. A model pin of an organization or a repository is
octopus-review or empty, and the octopus virtual key lists no Claude model. The fork still hard-codes Claude ids in some
utility paths, which the DB settings do not override. Issue #2270 tracks the fork patch that
removes them.
GitHub App (octopus-fzymgc)
Section titled “GitHub App (octopus-fzymgc)”The app id, private key, client id and client secret live in Vault at
fzymgc-house/cluster/octopus (github_app_id, github_app_private_key, github_client_id,
github_client_secret) and reach the pod through the octopus-app ExternalSecret.
- The callback URL must be
https://octopus.fzymgc.house/api/github/callback. Octopus runs the GitHub App user-authorization flow at this URL to prove that the installing user can access the installation. If either client value is missing, a connect or reinstall fails with “GitHub verification needs configuration”. If the callback URL is wrong, GitHub reportsredirect_uri_mismatch. - The setup URL must be
https://octopus.fzymgc.house/api/github/callbackwith “Redirect on update” enabled. Without it, GitHub never redirects back after an install, the signed-statecallback never fires,organizations.githubInstallationIdis never written, and repositories do not sync. - Always connect installations from octopus (“Connect GitHub” per org), never from GitHub’s
settings page. That path has no
stateand cannot link. - One octopus org maps to one GitHub installation (
githubInstallationIdis unique). A user can own any number of octopus orgs (MAX_OWNED_ORGS_PER_USER=0). Create one per GitHub account or org to review. - The webhook secret cannot be read back from GitHub. To rotate it,
PATCH /app/hook/configwith an app JWT andvault kv patch … github_webhook_secret=…with the same value, then force the ESO refresh. Webhook 401s mean that the two sides disagree. octopus-fzymgc[bot]is the approver of a clean pull request. With the organization settingapproveCleanReviewson (Settings > Reviews), itsAPPROVEreview counts toward the one approving review that the rulesetmain-branch-protectionrequires. GitHub dismisses that approval on every push, and the re-review approves again or leaves a comment. The ruleset also requires an approval from someone other than the last pusher, so Sean’s own approval does not count on a branch that he pushed, and Octopus is the approver.
Model configuration
Section titled “Model configuration”Models live in the Octopus database (available_models and org defaults), not in GitOps. All are
registered with provider=openai, which makes octopus’s ai-router use the OpenAI client (to
LiteLLM). An unregistered model id without a gpt prefix falls back to the Anthropic client and
fails.
Every string octopus sends must be on the octopus virtual key’s models list. The chat names
octopus-review and octopus-utility are LiteLLM lanes, so the key holds no alias for them. For
each other string, the key’s aliases map the string onto the lane that serves it. The key body
is tf/litellm/main.tf, and the lane names are model_name entries in
argocd/app-configs/litellm-chart/values.yaml.
The lane in values.yaml is the record of the model behind a chat name. The Octopus UI shows the
chat name and the price of its row in available_models, not the model. The spend of the
octopus key in LiteLLM is the record of the cost. To change the model, see
Change the review model.
The active chat rows are octopus-review and octopus-utility only. The octopus key refuses
every other chat name with HTTP 403, so do not make another chat row active.
An upstream migration can add an active chat row. After an upgrade of the fork, make such a row
inactive on the primary of the main cluster:
P=$(kubectl --context fzymgc-house -n postgres get cluster main -o jsonpath='{.status.currentPrimary}')kubectl --context fzymgc-house exec -i -n postgres "$P" -c postgres -- psql -d octopus <<'SQL'UPDATE available_models SET "isActive" = false WHERE category = 'llm' AND "modelId" NOT IN ('octopus-review', 'octopus-utility');SQLModel string (available_models) |
Lane and alias target | Category | Role |
|---|---|---|---|
octopus-review |
the lane octopus-review |
llm | platform default and the model pin of each organization. It serves the review, the analyzer, the request for missing findings and the Slack reply |
octopus-utility |
the lane octopus-utility (reasoning off) |
llm | utility model, set by OCTOPUS_UTILITY_MODEL: two-pass validation, feedback classification, repository configuration extraction, the chat guard and the chat routes |
ollama/bge-m3 (also bge-m3, and octopus’s hard-coded text-embedding-3-large default) |
octopus-embed |
embedding | org default embed model (1024 dimensions) |
The full key body, aliases included, is in
LiteLLM, Minting and scoping virtual keys, octopus. Avoid model
ids containing codex. Octopus routes them to the OpenAI Responses API, which LiteLLM does not
serve for this consumer. Do not set an org Anthropic key.
The upstream migrations add provider=anthropic rows, such as claude-opus-5 and
claude-opus-5-5. They are inactive. No Anthropic key exists, and the octopus virtual key does
not list them.
A daily pg-boss job, discover-models, runs at 07:00 UTC and lists the model catalog of each
provider that has an instance key. Only OPENAI_API_KEY is set, and OPENAI_BASE_URL sends it to
LiteLLM, so the job lists LiteLLM models only. The job does not activate models or change
defaults.
Fork state (seanb4t/octopus)
Section titled “Fork state (seanb4t/octopus)”The fork is a thin staging ground for upstreamable patches. Two stacked branches sit on the
upstream v1.3.1 tag, and the cluster image builds from the top one:
upgrade/v1.3.1-infra: the deployment patches in the first table.upgrade/v1.3.1-analysis: that branch plus the analysis features in the second table.
The upgrade/v1.2.14-* branches stay unchanged as the rollback point. See
Roll back to the previous fork release.
| Change | Cluster env |
|---|---|
db:deploy script and a migrator image stage (prisma migrate deploy) |
initContainer command |
Multi-arch GHCR build (.github/workflows/build-image.yaml in the fork) |
none |
Better Auth genericOAuth provider, runtime-gated on the login page, plus the social-login switch |
OIDC_DISCOVERY_URL, OIDC_PROVIDER_ID=authentik, OIDC_CLIENT_ID/SECRET (Vault octopus-oidc, written by tf/keycloak/octopus.tf), OIDC_PROVIDER_NAME, DISABLE_SOCIAL_LOGINS=true |
EMBEDDING_BATCH_ITEMS sets the OpenAI-path batch size |
EMBEDDING_BATCH_ITEMS=64 |
DISABLE_REVIEW_BRANDING removes the review footers |
DISABLE_REVIEW_BRANDING=true |
MAX_OWNED_ORGS_PER_USER from env, with <= 0 as unlimited at every limit check |
MAX_OWNED_ORGS_PER_USER=0 |
OCTOPUS_REVIEW_MAX_TOKENS sets the output token budget of one review request (image default 8192). Reasoning tokens count against the budget. See The 300-second limit of a review call before a change. Upstream since #879 |
OCTOPUS_REVIEW_MAX_TOKENS=49152 |
OCTOPUS_UTILITY_MODEL replaces the hard-coded Claude IDs of the utility calls (two-pass validation, feedback classification, repository configuration extraction, the chat guard and the chat routes). The value is a LiteLLM lane and a row of available_models |
OCTOPUS_UTILITY_MODEL=octopus-utility |
| Lone UTF-16 surrogates are replaced in the review request and on the OpenAI-compatible providers, so a diff cut inside an emoji does not get a 400 from the API. Upstream since #877 | none |
| The assessment validator accepts a suffix on the report heading and an Overall row without bold cells, and counts only a row whose first cell is Overall. It logs only the reason when it rejects a response. Upstream since #878 | none |
| The assessment validator derives the Overall score from the lowest numeric category score when the Overall row is missing or says N/A. With complete input, a Not assessed Overall counts as N/A. If every category is N/A, an N/A Overall is valid | none |
The organization setting approveCleanReviews (Settings > Reviews, off by default) posts an APPROVE review when a review finds nothing: zero findings after the filters and complete coverage, and every earlier Octopus inline comment outdated or replied to by a person. A pull request whose changed files are all excluded by .octopusignore gets the approval too, with no model assessment. GitHub only. Upstream pull request #931 is closed. The patch stays on the fork. |
none |
Unset optional services are skipped in silence: the Pubby realtime client sends nothing without its three variables, and the Elasticsearch sync log is a no-op without ELASTICSEARCH_URL. A review by a deleted account no longer stops the read of earlier reviews. The Prisma adapter pool logs a lost connection as [db] pool error: instead of raising an uncaught exception |
OCTOPUS_SERVER_ID from the pod name, so the claim log names the pod |
An inline comment uses a ```suggestion block only when the suggestion is replacement text for the anchored lines. A sed expression, an advice sentence, or a text whose tokens are mostly absent from the anchored lines is posted under a Suggested change label in a plain code block, which GitHub does not offer to apply. The prompt rule for the suggestion field says the same |
none |
The validator drops prose after the rows of the Findings Summary table and logs Dropped N line(s) after the Findings Summary table. A response rejected for a presentation reason (headings, Score table, Findings Summary table) gets one repair request that returns the rejected review with the reason. The log line Response repaired: marks a success. A findings JSON problem keeps the findings recovery request, and a capacity-admitted review gets no repair |
none |
Every completed attempt records a git patch-id style fingerprint of the prepared diff in its coverage and an outcome in the outcome column of review_attempts (migration 20261016220000_add_review_attempt_outcome). A push whose fingerprint equals the one of the last completed attempt, with the same model and a new head, reuses that attempt: no model call, no inline comment, one review that names the earlier commit, the check run of that attempt with the title unchanged since <sha>, and the approval back under the same gate. The log line is Diff unchanged since <sha>. A comment @octopus review always runs the model. The upstream table review_attempt_outcomes records a reused attempt with the kind substantive |
none |
Feature on upgrade/v1.3.1-analysis |
Cluster env |
|---|---|
File recency: a bare, blob-less clone and git log --name-status date each file, and indexing stores lastModifiedAt on every chunk |
INDEX_FILE_RECENCY=true (optional INDEX_FILE_RECENCY_WINDOW) |
Doc-aware analysis: structured chunk selection (documentation cap, path diversity, recency), a ## Documentation Accuracy section and doc-skeptical prompt framing |
none |
| Recency-aware review context: age annotations and stale-documentation demotion in both review context paths | none |
Two paths do not use file recency. Forgejo repositories are not scanned, because upstream runs
no git subprocess against a user-supplied Forgejo host, so their chunks read “age unknown”. And
lib/review-validation.ts, the pass that checks findings against code, formats its own context
without age annotations.
Image build: .github/workflows/build-image.yaml in the fork runs on a push to either branch. It
bakes NEXT_PUBLIC_GITHUB_APP_SLUG=octopus-fzymgc, NEXT_PUBLIC_OCTOPUS_SELF_HOSTED=true (no
billing path, as the upstream self-host image) and NEXT_PUBLIC_APP_VERSION. The login
configuration is runtime env, not a build argument. The cluster Deployment pins the web and
migrate digests from that build.
Moving to a new upstream release:
- Create
upgrade/<tag>-infrafrom the upstream tag, and cherry-pick the commits of the current infra branch withgit cherry-pick -x. If the cluster needs fixes that upstream merged after the tag, start from upstreammasterinstead. - Create
upgrade/<tag>-analysison top of it, and cherry-pick the commits of the current analysis branch. - If a conflict shows that upstream now covers a change, drop the change. If upstream rewrote the code around a change, read the change’s combined diff and apply it to the new code, rather than resolving it hunk by hunk.
- Run the unit tests and the opt-in PostgreSQL suites of upstream on both branches. The
agent-task-postgresjob in.github/workflows/ci.ymllists the variables that turn the suites on. Make the schema of the throwaway database withbun run db:push, becauseprisma migrate deployfails on an empty database. A fork patch can break one of those test harnesses with no merge conflict. - Point the workflow trigger at the new branch, push, and repoint the digests in a cluster PR.
- Before the rollout, rehearse the migrations on a
pg_dumpof the octopus database. See Schema migrations.
The repository skill octopus-fork-upgrade in .claude/skills/ runs this procedure, the
rehearsal and the rollout check for an agent.
Each stack branch is a candidate upstream pull request.
Embedding pipeline limits
Section titled “Embedding pipeline limits”Change any of these and indexing breaks:
| Layer | Setting | Why |
|---|---|---|
| octopus batch size | EMBEDDING_BATCH_ITEMS=64 |
The upstream default of 512 with chunks of about 24k characters makes each embeddings request large and slow. 64 keeps every response small and each request short, and the octopus-embed lane’s settings in values.yaml are sized for that batch |
| encoding_format | must pass through to the lane’s upstream | openai-node silently requests base64. Stripping the parameter makes the SDK mis-decode float arrays 4:1 (1024 to 256 dimensions, and Qdrant rejects). Do not add a drop-encoding_format transformation anywhere on the path |
The lane’s timeout and retry behaviour is LiteLLM’s, configured per lane in values.yaml.
Operations
Section titled “Operations”The 300-second limit of a review call
Section titled “The 300-second limit of a review call”The review call does not stream. Node’s fetch drops a call that sends no headers in 300 seconds,
and Octopus logs Request timed out. The OpenAI client of the fork then sends the same call two
more times. LiteLLM and the provider finish a call that Octopus dropped, so OpenRouter bills each
attempt in full. If the third attempt also fails, the check run Octopus Review fails.
A reply that uses the whole budget of OCTOPUS_REVIEW_MAX_TOKENS fails the check run too. Octopus
treats a finish_reason other than stop as an incomplete review.
Reasoning tokens count as output tokens, and on a large diff they are most of the output. Do not
lower OCTOPUS_REVIEW_MAX_TOKENS to make a call end sooner. The model then uses the whole budget
for reasoning and returns no review text.
Three fields of the span chat octopus-review in default.otel_traces show a call at the limit:
| Field | What it shows |
|---|---|
Duration |
A value over 300e9 (nanoseconds) is a call that Octopus dropped |
SpanAttributes['gen_ai.usage.output_tokens'] |
The reasoning tokens plus the reply tokens. A value equal to the budget is a reply that was cut off |
SpanAttributes['gen_ai.response.finish_reasons'] |
length is a reply that used the whole budget |
The span name holds the lane, not the model. To read the model, use
SpanAttributes['litellm.provider.model']. A filter on a span name that holds a model returns no
rows for a named lane.
This query reads one day of review calls. Run it with clickhouse-client on the ClickHouse pod of
the clickstack namespace:
SELECT count() AS calls, round(quantile(0.99)(o)) AS p99_out, round(quantile(0.1)(o / d), 1) AS p10_rate, least(49152, floor(quantile(0.1)(o / d) * 270 / 1024) * 1024) AS budget, max(i) AS max_inFROM ( SELECT toFloat64OrZero(SpanAttributes['gen_ai.usage.output_tokens']) AS o, toFloat64OrZero(SpanAttributes['gen_ai.usage.input_tokens']) AS i, Duration / 1e9 AS d FROM default.otel_traces WHERE Timestamp > now() - INTERVAL 1 DAY AND ServiceName = 'litellm' AND SpanName = 'chat octopus-review' AND SpanAttributes['gen_ai.request.max_tokens'] = '49152' AND toFloat64OrZero(SpanAttributes['gen_ai.usage.output_tokens']) > 1000)Set the value of gen_ai.request.max_tokens in the filter to the current
OCTOPUS_REVIEW_MAX_TOKENS. The lane also serves smaller calls, and the filter keeps the reviews
only.
| Column | Meaning |
|---|---|
p99_out |
The output tokens of the largest reviews of the day |
p10_rate |
The output tokens per second of a slow call |
budget |
The tokens that a slow call produces in 270 seconds, with an upper limit of 49152 |
max_in |
The input tokens of the largest call of the day |
If budget is under p99_out, the lane is too slow for its own replies. Do not lower
OCTOPUS_REVIEW_MAX_TOKENS in that case. Change the lane as
Change the review model describes.
Read the result only from a day that held a large diff. If max_in is under 60,000, the day held
no large diff, and the result says nothing about one. The slow calls come from large diffs, so a
quiet day always passes.
This query counts the findings per review for one week. Set the interval to cover the period, and
set the token budget in spans to the value of that period:
WITH spans AS ( SELECT 1 AS k, Timestamp + toIntervalNanosecond(Duration) - toIntervalSecond(1) AS t0 FROM default.otel_traces WHERE Timestamp > now() - INTERVAL 7 DAY AND ServiceName = 'litellm' AND SpanName = 'chat octopus-review' AND SpanAttributes['gen_ai.request.max_tokens'] = '49152' AND Duration < 295e9), generated AS ( SELECT 1 AS k, Timestamp AS lts, toUInt32OrZero(extract(Body, 'chars, ([0-9]+) findings')) AS findings FROM default.otel_logs WHERE Timestamp > now() - INTERVAL 7 DAY AND ServiceName = 'octopus' AND startsWith(Body, '[reviewer] Review generated:')), split AS ( SELECT 1 AS k, Timestamp AS sts, extract(Body, 'severities: (.*)$') AS sev FROM default.otel_logs WHERE Timestamp > now() - INTERVAL 7 DAY AND ServiceName = 'octopus' AND startsWith(Body, '[reviewer] Split:')), sg AS ( SELECT s.t0, g.lts, g.findings, 1 AS k FROM spans s ASOF LEFT JOIN generated g ON s.k = g.k AND g.lts >= s.t0 WHERE g.lts > toDateTime64('2000-01-01 00:00:00', 9) AND g.lts <= s.t0 + toIntervalSecond(4)), j AS ( SELECT sg.findings, if(p.sts > toDateTime64('2000-01-01 00:00:00', 9) AND p.sts <= sg.lts + toIntervalSecond(120), p.sev, '') AS sev FROM sg ASOF LEFT JOIN split p ON sg.k = p.k AND p.sts >= sg.lts)SELECT count() AS reviews, round(avg(findings), 2) AS avg_findings, sum(countSubstrings(sev, '🔴')) AS critical, sum(countSubstrings(sev, '🟠')) AS high, sum(countSubstrings(sev, '🟡')) AS medium, sum(countSubstrings(sev, '🔵')) AS lowFROM jThe query matches each review call to the log line Review generated that follows it within 4
seconds, and that line to the next Split line within 120 seconds.
Change the review model
Section titled “Change the review model”The lane octopus-review in argocd/app-configs/litellm-chart/values.yaml holds the model, the
reasoning effort and the provider rule of every review call. A model change needs no change to
the octopus key, to the Deployment or to the Octopus database.
-
Change
model:orreasoning_effort:of the laneoctopus-reviewin a pull request. -
After the merge, make sure that ArgoCD synced the
litellmApplication. -
Send one request for
octopus-reviewwith theoctopuskey from a workstation:Terminal window export VAULT_ADDR=https://vault.fzymgc.houseKEY="$(vault kv get -field=api_key secret/fzymgc-house/cluster/litellm-keys/octopus)"curl -s https://llm.fzymgc.house/v1/chat/completions \-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \-d '{"model":"octopus-review","max_completion_tokens":2048,"messages":[{"role":"user","content":"Reply with the word OK."}]}' \| jq '{provider, finish: .choices[0].finish_reason, usage}'The reply must name a provider and end with
stop. -
After a day that held a large diff, run the first query of The 300-second limit of a review call.
-
After one week, run the findings query of the same section, and compare the result with the week before the change.
The price in the row octopus-review of available_models can differ from the price of the new
model. Octopus uses that price only for its own cost display.
Rotate the LiteLLM virtual key
Section titled “Rotate the LiteLLM virtual key”In-place regeneration is not available. The procedure is revoke and re-mint under the same alias
(octopus), with a short outage, and it is documented once in
LiteLLM, Rotating a virtual key. In outline:
/key/delete the old key, /key/generate the replacement with the same body (the alias, the
models list and the aliases map from tf/litellm/main.tf), then write the new value to the
property octopus reads:
vault kv patch secret/fzymgc-house/cluster/litellm-keys/octopus api_key="<new key>"kubectl -n octopus annotate externalsecret octopus-app force-sync="$(date +%s)" --overwriteThe Deployment carries reloader.stakater.com/auto: "true", so the pod restarts on its own once
ESO writes the Secret. Make sure of it with kubectl -n octopus rollout status deploy/octopus
rather than restarting by hand.
Update the fork image
Section titled “Update the fork image”# after the upgrade branch builds:docker buildx imagetools inspect ghcr.io/seanb4t/octopus:<sha> | grep Digest# repoint both digests in argocd/app-configs/octopus/deployment.yaml, PR + mergeRoll back to the previous fork release
Section titled “Roll back to the previous fork release”- Find the web and migrate digests of the previous release in the git history of
argocd/app-configs/octopus/deployment.yaml. - Repoint both digests in a cluster PR, and merge it.
- If the previous release is older than upstream v1.2.17, reindex each repository: Cancel and re-index from the repository page.
The older image runs on the migrated schema when the newer migrations only add columns, tables and indexes. The eight migrations from v1.2.14 to v1.3.1 are of that kind, so that rollback needs no database restore.
A release older than v1.2.17 reads only the Qdrant points of the plain repository ID. Those points stop changing at the first full index under the newer release, so they are stale until the reindex. See Index generations in Qdrant.
Index generations in Qdrant
Section titled “Index generations in Qdrant”Since upstream v1.2.17, a full index writes the chunks of a repository to a new index generation.
An index generation is one complete set of the chunks of one repository. The
activeIndexGeneration column of the repository row names the generation that reviews read. An
incremental index changes the active generation in place.
The points of a generation carry it in the indexGeneration payload field. Their repoId
payload field holds the JSON array ["<repository id>","<generation>"]. Older releases filter
and delete on the plain repository ID, so they do not see these points. A repository with no full
index since the upgrade keeps its points under the plain ID.
Octopus does not delete an earlier generation. Each full index leaves one more copy of the
chunks of the repository in qdrant-octopus, and no cleanup procedure exists yet. After a full
index, look at the use of the qdrant-octopus PVC.
Backfill file-recency metadata
Section titled “Backfill file-recency metadata”lastModifiedAt is stamped on chunks at index time (gated by INDEX_FILE_RECENCY). A repository
indexed without it reads as “age unknown” (no age annotations, no stale-doc demotion) until it is
re-indexed: Cancel and re-index from the repository page. The selection and prompt improvements
(doc-aware context, ## Documentation Accuracy) apply regardless. Only age-awareness needs the
re-index.
Schema migrations
Section titled “Schema migrations”The migrate initContainer runs prisma migrate deploy on every pod start. Upstream migrations
can insert or update rows, for example the seed rows in available_models. prisma db push
skips those statements, so do not use it on this database.
The database has no migration history before the Jira migration, so the container first records
20260419212831_add_jira_integration as applied. On later starts that command fails with
“already recorded as applied”, and the script accepts that one failure. Any other failure stops
the pod.
To rehearse an upgrade on a copy of the database:
P=$(kubectl -n postgres get cluster main -o jsonpath='{.status.currentPrimary}')kubectl -n postgres exec "$P" -c postgres -- pg_dump -Fc --no-owner --no-acl -d octopus > octopus.dumpdocker run -d --name octpg -p 55432:5432 -e POSTGRES_PASSWORD=pw -e POSTGRES_DB=octopus postgres:18docker exec -i octpg pg_restore -U postgres -d octopus --no-owner --no-acl < octopus.dump# in packages/db of the new fork branch:export DATABASE_URL=postgresql://postgres:pw@localhost:55432/octopusbunx prisma migrate deploybunx prisma migrate diff --from-config-datasource --to-schema prisma/schema.prisma --scriptThe last command must print -- This is an empty migration.
To make sure that a rollback works, run bunx prisma migrate deploy against the same copy from
packages/db of the previous fork branch. It must print No pending migrations to apply.
Delete the dump after the rehearsal, because it holds application data.
Add another repository or GitHub org
Section titled “Add another repository or GitHub org”Same-account repositories: adjust the installation’s repository selection on the GitHub side, then Sync in octopus. New GitHub account or org: create a new octopus org (org switcher, Create Organization), Connect GitHub from that org, install, and it links and syncs.
Stop reviews
Section titled “Stop reviews”kubectl -n octopus scale deploy/octopus --replicas=0# data is isolated to the octopus DB + qdrant-octopus PVC — no blast radius into# engram/agent-memory. Uninstall the GitHub App to stop webhooks entirely.Troubleshooting
Section titled “Troubleshooting”| Symptom | Check |
|---|---|
| Webhook deliveries 401 | Webhook secret mismatch between the App and Vault. Rotate both sides (see the GitHub App section) |
| Repositories do not appear after install | Installed from GitHub’s settings page (no state) or the setup URL is missing, so organizations.githubInstallationId is null. Reconnect through octopus’s Connect GitHub |
| Index stuck at “Indexing…”, pod idle | The fire-and-forget index task died without updating status (its progress logs go to the unconfigured pubby and ElasticSearch writers, not stdout). Check Failed to index repo in the pod logs, then Cancel and re-index |
| Embed 503 or 504 | See Embedding pipeline limits. Watch the LiteLLM — spend by key alias and LiteLLM — request latency p95 by model tiles on the LiteLLM — LLM & key usage HyperDX dashboard filtered to key alias octopus, and the octopus-embed rows in otel_traces |
| Qdrant “expected dim 1024, got 256” | encoding_format is being stripped on the way to the lane (see the limits table) |
Redirect loop to /complete-profile |
Stale current_org_id browser cookie pointing at a deleted org. Clear the cookie. Do not submit the form, which creates a duplicate org |
Failed to trigger event or sync log to ES log spam |
Unconfigured pubby and ElasticSearch writers. Cosmetic |
| Octopus Review check red with no findings | Read the check-run output first. The check fails on its own errors too, for example an assessment that came back cut off or malformed. A red check is not a review finding |
| Octopus Review check red with “Review incomplete — input coverage missing” | The PR has more changed text than the review budget (MAX_DIFF_CHARS, 350,000 characters), or GitHub sent a file without a patch. Add paths that need no review to .octopusignore at the repository root. Octopus reads the file from the PR base commit, so a change applies only after it merges. Do not use .gitattributes for this. Octopus still reviews code and YAML files that it marks as generated |
| Octopus Review check red with “Input complete — assessment invalid or unavailable” | The model response failed the format validator twice: the pod log holds two [review-assessment] Response rejected: lines with the reasons, the first for the response and the second for the one repair request. A completion=length reason means the output budget cut the response, see OCTOPUS_REVIEW_MAX_TOKENS. A Findings JSON reason gets no repair and goes to the findings recovery request. Comment @octopus review on the pull request for a new attempt |
Octopus Review check red, and the pod logs Review failed with Request timed out |
The review call ran past 300 seconds three times. See The 300-second limit of a review call |
| Review never posts | kubectl -n octopus logs deploy/octopus ([reviewer] lines). Make sure that the model string is on the octopus key’s models list (a missing string is a LiteLLM 403, not a model error) and that available_models has it with provider=openai |
| Image pull fails | ghcr-pull-secret ExternalSecret in the octopus namespace (private seanb4t image) |
ExternalSecret SecretSyncedError after a spec change |
ArgoCD SSA spec.data lag. Delete the ExternalSecret (ArgoCD self-heals it fresh). Deleting only the target Secret is not enough |
References
Section titled “References”- Secrets:
docs/reference/secrets.md(secret/fzymgc-house/cluster/octopus,…/octopus-oidc,…/litellm-keys/octopus) - Manifests:
argocd/app-configs/octopus/, Applicationargocd/cluster-app/templates/octopus.yaml - Keycloak OIDC client:
tf/keycloak/octopus.tf - LiteLLM key:
tf/litellm/main.tf - Design:
docs/engineering/specs/2026-06-06-octopus-self-host-design.md