Installation

Scarab is Kubernetes-only by design, so Helm is the install path for a cluster. The chart deploys scarab-server (one binary, selectable roles) with the RBAC it needs to launch one Pod per step in its namespace.

The same chart targets any Kubernetes: a local kind/colima cluster or a real, live cluster. just local-helm (below) is just a convenience loop that installs this chart on colima; a live cluster uses the same helm upgrade --install with your own Postgres, object store, and credentials. The chart is young and gains production hardening as it earns mileage, but nothing about it works only locally.

The chart

The chart lives at deploy/helm/scarab/ (Chart.yaml, values.yaml, templates/). It expects:

• Postgres: the durable coordination substrate; without it the server serves the API only.
• An S3-compatible object store (AWS S3 or in-cluster MinIO) for logs, artifacts, and the content-addressed workspace snapshots reruns restore; a fallback to a local directory exists for development.
• The published image ghcr.io/thulasi-ram/scarab-server, built by .github/workflows/image.yml. Use the mutable edge tag or a pinned sha-<gitsha>.

A direct install:

helm upgrade --install scarab deploy/helm/scarab \
  --namespace scarab --create-namespace \
  --set image.tag=edge \
  --set secrets.databaseUrl='postgres://scarab:scarab@postgres.scarab.svc:5432/scarab' \
  --set scarab.s3.bucket=scarab-logs \
  --set scarab.s3.endpoint=http://minio.scarab.svc:9000 \
  --set secrets.s3AccessKey=scarab --set secrets.s3SecretKey=scarabsecret

For production, keep credentials out of --set: create a Secret whose keys are the SCARAB_* environment-variable names and reference it with secrets.existingSecret.

The GitHub App private key is the one credential with a bootstrap ordering problem — storing it through the API needs a server that is already running, and it dies with the database. So the chart can mount it from a Secret you manage out-of-band instead, and the server reads it at boot:

kubectl -n scarab create secret generic scarab-github-app \
  --from-file=github-app.pem=./my-app.private-key.pem
# then: --set scarab.githubAppId=123456 \
#       --set secrets.githubAppPemSecret.name=scarab-github-app

A boot-supplied key overrides any stored _forge credential and survives a database recreate. The installations it authenticates as are separate durable state, registered from the App’s installation webhook deliveries.

Two App settings that fail silently

A correct webhook URL and secret are not enough. Both of these produce a loop that looks healthy and has no error anywhere:

• Subscribe to events (App → Permissions & events → Subscribe to events): check Push and Pull request. With the list empty, push/pull_request are never delivered so nothing ever runs — yet installation and installation_repositories still arrive (App-management events are independent of the subscription list), so the connection registers and GET /v1/repos looks fine. The symptom reads as “the repo is registered but no run ever starts.”
• Commit statuses: read & write (App → Permissions → Repository): without statuses:write every status post is rejected 403 Resource not accessible by integration. The run itself still succeeds, so the only visible effect is a pull request that never shows a Scarab status. Add Checks: read & write only if you use checks; Contents: read is what a clone step needs.

You do not have to verify these by eye: Settings → Connections runs a preflight against the App and names whatever is missing (GET /v1/connections/{id}/preflight), so a misconfigured App reads as unhealthy rather than as silence. Note that a permission change is not live until an installation owner approves the new access (GitHub emails them) — until they do, the preflight keeps reporting the gap.

Key values

Only keys that exist in values.yaml:

Key	Default	Notes
image.repository / image.tag	ghcr.io/thulasi-ram/scarab-server / appVersion	container image
scarab.role	converged	api / scheduler / executor / webhook / converged
scarab.executor	k8s	k8s (prod) or local (dev only)
scarab.namespace	release ns	namespace step Pods launch into (RBAC granted there)
scarab.s3.*	—	object store; set bucket to enable S3/MinIO
secrets.* / secrets.existingSecret	—	sensitive SCARAB_* env (DB URL, S3 keys, master key, webhook secrets)
secrets.githubAppPemSecret.name / .key	— / github-app.pem	mount the GitHub App private key from your own Secret
rbac.create	true	Role/RoleBinding for Pod execution
ingress.enabled	false	expose the HTTP API

See deploy/helm/scarab/README.md and values.yaml for the full surface.

A minimal values.yaml

A representative override for a real cluster, where Postgres and S3 credentials come from a Secret you manage out-of-band (secrets.existingSecret), not inline:

image:
  tag: sha-<gitsha>        # pin an immutable published tag; `edge` tracks main

scarab:
  role: converged          # or split: api / scheduler / executor / webhook
  executor: k8s
  publicUrl: https://scarab.example.com   # run deep-link in commit statuses
  s3:
    bucket: scarab-artifacts
    endpoint: ""           # empty => AWS S3; set for in-cluster MinIO
    region: us-east-1

secrets:
  # Keys in this Secret must match the SCARAB_* env-var names
  # (e.g. SCARAB_DATABASE_URL, SCARAB_S3_ACCESS_KEY, SCARAB_MASTER_KEY,
  #  SCARAB_GITHUB_WEBHOOK_SECRET).
  existingSecret: scarab-env

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: scarab.example.com
      paths:
        - path: /
          pathType: Prefix

Every key above exists in the chart’s values.yaml; see it (and README.md) for the full reference.

The colima local loop

just local-helm installs the same chart on a local colima cluster and brings the whole stack up inside the cluster: Postgres, MinIO, and scarab-server (which also serves the web UI at /), so you can repeatedly deploy a pinned image and watch this repo’s own CI run on Scarab.

just local-helm             # deploy the latest ghcr `edge` image
just local-helm sha-<sha>   # deploy a specific published SHA
just local-helm local       # build server + clone + sidecar from the tree, then deploy
just local-helm-ui 8080     # port-forward the in-cluster UI (reconnects across deploys)

The kube context must be colima (the deploy script refuses otherwise). Configuration (image source, GitHub App knobs, webhook secrets, seed inputs) lives in one gitignored file, deploy/local-helm/.env; see deploy/local-helm/README.md for the steps to configure the App and the caveats about the object store.

For a workflow that stays on your laptop with no cluster at all, Run locally is the lightest way to exercise the system.

References

• ADR-0005: Tenancy & deployment: Kubernetes as the only backend