Skip to content

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.

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/
  1. GitHub sends a pull_request webhook to octopus-wh.fzymgc.net/api/github/webhook (HMAC-verified).
  2. Octopus enqueues a pg-boss process-review job. The in-process worker retrieves relevant code_chunks (dense plus sparse RRF) from Qdrant.
  3. 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.
  4. Findings post as inline comments with severity. Findings at or above the org’s checkFailureThreshold (default critical) submit the review as REQUEST_CHANGES. Otherwise the review is a COMMENT.
  5. 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 review always 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.

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 reports redirect_uri_mismatch.
  • The setup URL must be https://octopus.fzymgc.house/api/github/callback with “Redirect on update” enabled. Without it, GitHub never redirects back after an install, the signed-state callback never fires, organizations.githubInstallationId is 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 state and cannot link.
  • One octopus org maps to one GitHub installation (githubInstallationId is 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/config with an app JWT and vault 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 setting approveCleanReviews on (Settings > Reviews), its APPROVE review counts toward the one approving review that the ruleset main-branch-protection requires. 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.

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:

Terminal window
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');
SQL
Model 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.

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:

  1. Create upgrade/<tag>-infra from the upstream tag, and cherry-pick the commits of the current infra branch with git cherry-pick -x. If the cluster needs fixes that upstream merged after the tag, start from upstream master instead.
  2. Create upgrade/<tag>-analysis on top of it, and cherry-pick the commits of the current analysis branch.
  3. 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.
  4. Run the unit tests and the opt-in PostgreSQL suites of upstream on both branches. The agent-task-postgres job in .github/workflows/ci.yml lists the variables that turn the suites on. Make the schema of the throwaway database with bun run db:push, because prisma migrate deploy fails on an empty database. A fork patch can break one of those test harnesses with no merge conflict.
  5. Point the workflow trigger at the new branch, push, and repoint the digests in a cluster PR.
  6. Before the rollout, rehearse the migrations on a pg_dump of 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.

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.

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_in
FROM (
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 low
FROM j

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

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.

  1. Change model: or reasoning_effort: of the lane octopus-review in a pull request.

  2. After the merge, make sure that ArgoCD synced the litellm Application.

  3. Send one request for octopus-review with the octopus key from a workstation:

    Terminal window
    export VAULT_ADDR=https://vault.fzymgc.house
    KEY="$(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.

  4. After a day that held a large diff, run the first query of The 300-second limit of a review call.

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

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:

Terminal window
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)" --overwrite

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

Terminal window
# 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 + merge
  1. Find the web and migrate digests of the previous release in the git history of argocd/app-configs/octopus/deployment.yaml.
  2. Repoint both digests in a cluster PR, and merge it.
  3. 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.

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.

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.

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:

Terminal window
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.dump
docker run -d --name octpg -p 55432:5432 -e POSTGRES_PASSWORD=pw -e POSTGRES_DB=octopus postgres:18
docker 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/octopus
bunx prisma migrate deploy
bunx prisma migrate diff --from-config-datasource --to-schema prisma/schema.prisma --script

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

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.

Terminal window
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.
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
  • Secrets: docs/reference/secrets.md (secret/fzymgc-house/cluster/octopus, …/octopus-oidc, …/litellm-keys/octopus)
  • Manifests: argocd/app-configs/octopus/, Application argocd/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