Project Configuration¶

The configuration surface of the Project custom resource: what each field controls, its type, its default, and the behavior it selects. It is the companion to Your First Project, which covers the minimal Project only.

This page is organized by the thing being configured. For the same object presented as an API schema, including the .status surface and the fields no project normally sets, see the Project CRD reference. Where the two pages describe the same field they are describing the same field; the CRD reference is authoritative on type and shape.

API group / version: tatara.dev/v1alpha1 Kind: Project Scope: Namespaced

Required and key top-level fields¶

scmSecretRef is the only field the API requires at the top level. Within spec.scm, provider, owner, and botLogin are required.

SCM Secret format¶

The Secret must exist in the Project's namespace before the Project is applied.

apiVersion: v1
kind: Secret
metadata:
  name: tatara-scm
  namespace: tatara
type: Opaque
stringData:
  token: "ghp_..."   # bot PAT: contents, issues, pull requests, metadata, org members read
                     # (GitHub fine-grained) or api + read/write_repository (GitLab). No webhook scope.

No webhook scope is needed: the operator never registers webhooks. It validates inbound payloads against a separately configured secret.

Memory sizing¶

Each Project gets a dedicated memory stack: a CNPG-managed PostgreSQL cluster, a Neo4j graph database, a LightRAG graph indexer, and the tatara-memory API server the other components query. The stack persists the code-knowledge graph agents traverse at runtime.

graph TD
    CR["Project CR"] -->|reconcile| OP["tatara-operator"]
    OP -->|provisions| PG["CNPG Cluster\n(pgInstances replicas,\npgStorage / pgWalStorage)"]
    OP -->|provisions| N4J["Neo4j StatefulSet\n(neo4jStorage)"]
    OP -->|provisions| LR["LightRAG\n(graph indexer)"]
    OP -->|provisions| MEM["tatara-memory\n(API server)"]
    PG & N4J & LR --> MEM
    MEM -->|all components healthy| RD["status.memory.phase = Ready"]
    RD --> WH["status.webhookURL available\nRepository ingestion unblocked"]

Scaling guidance:

• Development or a single repository: the defaults are sufficient for evaluation.
• Production, multiple repositories: set pgInstances: 3 for PostgreSQL HA and raise storage to 20Gi or above once ingestion consistently reaches 80% of capacity. The live tatara self-hosting project runs pgInstances: 3, pgStorage: 10Gi, neo4jStorage: 10Gi across eight repositories.
• Large monorepos above 500k lines: start at neo4jStorage: 20Gi and pgStorage: 20Gi.

spec:
  memory:
    pgInstances: 3
    pgStorage: 20Gi
    pgWalStorage: 8Gi
    neo4jStorage: 10Gi

Memory readiness and what it gates¶

status.memory.phase is one of Provisioning, Ready, Degraded, Failed, or Disabled. status.memory.notReady names the stack components currently below their readiness gate (postgres, neo4j, lightrag, memory-api) and is empty when the stack is Ready.

Readiness is debounced. A consumer treats the stack as stably ready only after it has held Ready for three minutes, measured from status.memory.readySince. That debounce gates repository ingestion, the TATARA_MEMORY_DEGRADED pod environment variable, and the degraded turn-0 prompt appendix. It is not a pod-spawn gate: agent pods spawn and submit turns whatever the stack's phase, with the degradation declared to them, because an unbounded memory outage otherwise held every Task indefinitely.

During the debounce window a Repository carries a MemoryNotReady condition with message waiting for project <name> memory stack to become stably Ready even though status.memory.phase already reads Ready.

Agent configuration¶

spec.agent configures every agent pod the operator schedules for this Project. The fields below are the ones a project normally sets; see AgentSpec for the complete list, including the extra containers, volumes, MCP servers, and skill sources.

Deprecated agent fields¶

Four spec.agent fields are retained in the CRD with zero effect. They exist only so helmfile values that already set them keep validating; removal is a breaking API change reserved for a later major version. Setting any of them changes nothing.

Nothing in that group survives as a live field. The bound that people reach for here - "how many times does a human PR comment un-park a review-kind Task" - is real and is 5, but it is the MaxHumanReviewRounds constant in tatara-operator/api/v1alpha1/constants.go, not agent.maxHumanReviewRounds. Writing that key into a Project is pruned silently by the apiserver and changes nothing. The residency cap is a constant for the same stated reason: a bound that structural-schema pruning can drop is no bound at all.

spec:
  agent:
    model: claude-opus-4-8
    image: harbor.example.com/tatara-claude-code-wrapper:v1.2.3
    effort: xhigh
    turnTimeoutSeconds: 1800    # 30 minutes of inactivity, not wall-clock age
    stallProbeGraceSeconds: 300
    stallProbeMaxAttempts: 2

Lifecycle hooks¶

Optional shell commands the wrapper runs at fixed lifecycle points. Each is executed via sh -c. An empty field is skipped. A non-zero exit is logged and counted as a metric but never aborts the agent run.

spec:
  agent:
    hooks:
      preClone: "echo cloning $1"
      postClone: "mise install"
      conversationStart: "notify-start.sh"
      agentTurnFinished: "run-metrics-push.sh"

Approval and intake¶

The intake model determines which accounts can drive the agent loop. A separate allow-list determines which accounts can release an issue into implementation.

Approval is a comment, never a label. When the implement agent has settled the scope, a maintainer posts a comment. The agent judges whether that comment approves and cites it - its forge external_id plus a verbatim quote - in submit_outcome(action=approved), alongside the plan note it wants approved. The operator does not take the agent's judgment on faith. It independently verifies that the cited comment exists, that its author is a verified maintainer and not the bot, and that the quoted text occurs in the comment body the operator itself holds. It then pins the comment id on the Issue as single-use evidence and lets the work start. The operator holds no wordlist and never decides what a comment means.

What approves, and what does not¶

If no citation passes, the Task parks. Nothing is posted to the issue: the reason lives in the operator's logs and metrics, not on the thread, so no prompt tells anyone a comment is needed. A comment posted at any time afterwards un-parks the Task to a fresh implement pod, which picks up the conversation where it left off. See Approval Gates for the full rules, including why the cited comment need not be the thread's most recent one.

Allow-lists¶

Both lists are capped at 100 entries, and neither may contain scm.botLogin; the API rejects a Project that violates either constraint. Both are overridable per-repository via RepositorySpec.maintainerLogins and RepositorySpec.reporterLogins.

spec:
  scm:
    maintainerLogins:
      - alice
      - bob
    reporterLogins:
      - alice
      - bob

Label set¶

The operator projects a small set of labels onto an issue as a one-way, write-only mirror of Issue.status.status and the Task's state. The labels are useful for dashboards and for humans scanning an issue list, and no label is ever read back to derive that status. Defaults work without configuration; override only to match organizational naming conventions.

The old label fields that configured a label-driven approval trigger are removed from the CRD outright. See Project: Label set.

Merge policy¶

An agent-opened PR is never merged by an agent. Once a review pod calls submit_outcome(verdict=approve) from a separate pod that structurally cannot decide its own diff's fate on the forge, the operator reads the live PR head, posts a COMMENT-type review carrying the verdict, and merges it. The review is never a native forge APPROVE, because GitHub blocks a PR's own author from approving it and one bot identity makes that call fail with a 422.

No tatara-opened PR is ever created with the forge's own merge-when-green setting switched on; mergePolicy is evaluated inside the operator.

There is no SCM branch-protection rule that adds a human merge step on top of this. A rule requiring an approving review would deadlock every merge, because the platform cannot satisfy it on its own PR. Combining autoMergeOnGreenCI with a branch-protection rule that requires an approved review before CI can pass is the supported way to reinstate a human gate. See the accepted-risk note for what defense-in-depth looks like under one bot identity.

PR reaction scope¶

spec.scm.prReactionScope gates which human PRs and MRs the sweep's re-review path reacts to. It has no default, and unset is the widest setting rather than the narrowest.

Cron activities¶

All schedules use standard 5-field cron syntax. An empty schedule disables that activity. Five activities exist under spec.scm.cron.

spec:
  scm:
    cron:
      issueScan:
        schedule: "0 * * * *"   # every hour at :00
        maxPerRepo: 1            # concurrent issue-scan Tasks per repository lane

spec:
  scm:
    cron:
      brainstorm:
        enabled: true
        schedule: "0 * * * *"
        targetOpenProposals: 3   # backlog target the operator refills toward
        historyWindow: 20
        staleProposalDays: 14
        sources:                 # docs | memory | internet
          - docs
          - memory
          - internet

spec:
  documentation:
    enabled: true
    repo: https://github.com/my-org/my-docs
  scm:
    cron:
      documentation:
        schedule: "0 2 * * *"   # nightly at 02:00
        maxPerRepo: 1

spec:
  scm:
    cron:
      refine:
        schedule: "0 */6 * * *"
        closedLookbackDays: 30

spec:
  upgradePolicy:
    engine: none
    majorStrategy: nextHopOnly
  scm:
    cron:
      upgrade:
        schedule: "58 */4 * * *"
        maxOpenUpgrades: 1

Grafana incident-response integration¶

When enabled, the operator provisions a per-project grafana-mcp Deployment backed by a read-only Grafana Viewer service account, and exposes an alert-webhook receiver at <webhookURL>/grafana. Agent pods reach the deployment over the network via the TATARA_GRAFANA_MCP_URL env var the operator injects; it is a standalone in-cluster service, not a sidecar container in each agent pod. Grafana alert rules that POST to the webhook receiver trigger incident-response tasks.

spec:
  grafana:
    enabled: true
    url: http://prometheus-grafana.monitoring.svc.cluster.local
    secretRef: tatara-grafana

The referenced Secret must contain two keys:

apiVersion: v1
kind: Secret
metadata:
  name: tatara-grafana
  namespace: tatara
type: Opaque
stringData:
  serviceAccountToken: "glsa_..."   # Grafana Viewer SA token (mounted into grafana-mcp)
  webhookSecret: "..."              # bearer the Grafana contact point presents to the webhook

Project board projection¶

spec:
  scm:
    board:
      githubProjectNumber: 42
      statusField: Status

Project guidance¶

spec.scm.guidance is free-form text appended verbatim to the brainstorm goal context. It scopes the agents' focus area for this project.

spec:
  scm:
    guidance: >-
      Treat the helm charts, CI pipelines, and Kubernetes configuration as in-scope
      alongside application features. Prioritize reliability and observability
      improvements.

Queue tuning¶

Omit spec.queue entirely if the capacity derived from maxConcurrentAgents is sufficient.

Annotated full Project YAML¶

A production-shaped example for a GitHub organization, using the commonly set fields.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

apiVersion: tatara.dev/v1alpha1
kind: Project
metadata:
  name: my-project              # (1)!
  namespace: tatara
spec:
  scmSecretRef: tatara-scm      # (2)!
  triggerLabel: tatara          # (3)!
  maxConcurrentAgents: 5        # (4)!
  agentPodTTLSeconds: 3600      # (5)!
  maxLivePods: 2                # (6)!
  maxNewTasksPerSweep: 5
  maxOpenTasks: 6               # (7)!
  maxBundleBytes: 400000

  agent:
    model: claude-opus-4-8      # (8)!
    image: harbor.example.com/tatara-claude-code-wrapper:v1.2.3  # (9)!
    effort: xhigh               # (10)!
    turnTimeoutSeconds: 1800    # (11)!
    stallProbeGraceSeconds: 300
    stallProbeMaxAttempts: 2    # (12)!

  memory:
    pgInstances: 3              # (13)!
    pgStorage: 20Gi             # (14)!
    pgWalStorage: 8Gi
    neo4jStorage: 10Gi          # (15)!

  scm:
    provider: github            # (16)!
    owner: my-org               # (17)!
    botLogin: my-org-bot        # (18)!
    botEmail: 12345+my-org-bot@users.noreply.github.com  # (19)!
    maintainerLogins:           # (20)!
      - alice
      - bob
    reporterLogins:             # (21)!
      - alice
      - bob
    mergePolicy: afterApproval  # (22)!
    prReactionScope: labeledOrMentioned  # (23)!
    guidance: >-                # (24)!
      Focus on reliability and observability alongside new features.
    board:
      githubProjectNumber: 42
      statusField: Status
    cron:
      issueScan:
        schedule: "0 * * * *"
        maxPerRepo: 1           # (25)!
      brainstorm:
        enabled: true
        schedule: "0 * * * *"
        targetOpenProposals: 3  # (26)!
        historyWindow: 20
        staleProposalDays: 14   # (27)!
        sources:
          - docs
          - memory
          - internet
      documentation:
        schedule: "0 2 * * *"
      refine:
        schedule: "0 */6 * * *" # (28)!
        closedLookbackDays: 30

  documentation:
    enabled: true               # (29)!
    repo: https://github.com/my-org/my-docs

  grafana:
    enabled: true               # (30)!
    url: http://prometheus-grafana.monitoring.svc.cluster.local
    secretRef: tatara-grafana   # (31)!

  queue:
    capacity: 5                 # (32)!
    alertCapacity: 1            # (33)!

1. The Project name must be unique per namespace. It becomes the label tatara.dev/project on every downstream resource: agent pods, the memory stack, and the cron-driven Tasks.
2. Name of the Secret in the same namespace. It must contain key token with the bot PAT and must exist before the Project is applied.
3. Issues carrying this label enter the agent loop. Defaults to tatara.
4. The project's kill switch: maximum concurrent agent pods across all repositories. The admission unit is the pod-spawn, not the Task. 0 fully pauses the project - no QueuedEvent is admitted, so no pod and no Task is created.
5. Bounds one agent pod's life in seconds. The Task persists across as many pods as it needs; a pod that runs past this deadline is stopped with a guaranteed handoff note written to Task.status.notes, and a fresh pod resumes from it. Minimum 300.
6. Caps Tasks in a live conversational state. It is clamped to maxConcurrentAgents - 1 so open conversations cannot consume the entire concurrency budget.
7. Caps active Tasks, meaning every Task at a pod-eligible stage. A Task creation budget, separate from the pod concurrency budget above.
8. Claude model for all agent kinds in this Project, unless overridden per kind in modelByKind. Changing it affects new pods immediately; an in-flight pod continues on the model it started with.
9. Full image reference for the tatara-claude-code-wrapper container. The operator uses this value verbatim in every agent Pod spec, so pin an explicit tag or digest.
10. Reasoning effort. xhigh is the default and the recommended starting point. Lower values reduce API cost and also agent quality on complex multi-file implementation work.
11. Per-turn inactivity window in seconds. It does not kill the turn: past this long with no agent output the operator probes the agent, and only an unanswered probe sequence interrupts the session. A turn actively writing files or running tests is never probed.
12. Unanswered probes before the operator interrupts the session and runs the stop-and-handoff sequence. maxTurnsPerPod, maxTurnsPerTask, maxReviewRounds and maxPodRecreations are deprecated with zero effect and are omitted here on purpose; maxHumanReviewRounds is omitted because it is a package constant and has never been a field on this spec.
13. CNPG PostgreSQL replica count. 1 is acceptable for development; 3 gives HA and is the production setting.
14. PVC storage per PostgreSQL replica (PGDATA). Scale with the number and size of enrolled repositories.
15. PVC for the Neo4j graph database. The code-knowledge graph grows with total ingested line count across every enrolled repository.
16. SCM provider: github or gitlab.
17. GitHub organization name or GitLab group path, as it appears in repository URLs.
18. Username of the dedicated bot account. Its PAT must grant repository contents read and write, issues, pull requests, and org-membership read on all target repositories. No webhook-admin scope is needed; the operator never registers webhooks.
19. GitHub noreply commit-author email for the bot. It links agent commits to the bot account in the GitHub web UI, and is found in the bot account's GitHub email settings.
20. Human maintainer logins. Required for anything to ever be approved: empty means no approval is possible. Only a comment from one of these accounts can be cited as approval by the implement agent, and the operator verifies the citation independently. The set also forms the trusted-insider set for intake. Must not contain botLogin. Overridable per-repository.
21. Reporter allow-list. When set, issues and comments from accounts not in this list, not in maintainerLogins, and not the bot are dropped at intake. This closes the primary prompt-injection vector. Must not contain botLogin. Overridable per-repository.
22. Gate on the operator's own merge. afterApproval is the default and trusts the relayed approving signal; autoMergeOnGreenCI additionally requires green CI.
23. Scope of scheduled PR re-review. This example opts in to the narrow setting. Left unset, or set to all, the sweep re-reviews every open human PR or MR each cycle. The field has no default, so set it explicitly to narrow the loop.
24. Free-form project charter text appended verbatim to the brainstorm goal context. Use it to focus agent attention on this project's priorities.
25. Concurrent issue-scan Tasks per repository lane. 1 is the safe default; one scan agent per repository prevents conflicting concurrent scans.
26. The backlog target the operator refills toward across all repositories. It never closes a proposal to reconcile downward. The deprecated maxOpenProposals alias is honoured only while this field is unset.
27. Opts the staleness reaper into an explicit 14-day window: bot proposals with no human engagement for that long are auto-closed, keeping the backlog from filling with dead proposals. Unset enables a default window; a negative value disables the reaper.
28. Refine carries its own schedule. It is not a pre-step of the scan or brainstorm cycles, and an empty schedule disables it entirely.
29. The real on-switch for the nightly documentation agent, alongside documentation.repo. scm.cron.documentation.schedule above is a separate and also-required gate.
30. Enables the per-project Grafana integration: a read-only grafana-mcp Deployment provisioned with a Viewer service account token, reached by agents through the injected TATARA_GRAFANA_MCP_URL, plus an alert-webhook receiver at <webhookURL>/grafana.
31. Kubernetes Secret containing two keys: serviceAccountToken, the Grafana Viewer SA token mounted into the grafana-mcp container, and webhookSecret, the bearer token the configured Grafana contact point must present to the webhook.
32. Queue admission capacity: maximum simultaneously admitted normal-class events. Defaults to maxConcurrentAgents when unset. Override only to decouple queue capacity from the concurrency cap.
33. Reserved concurrent slots for alert-class events. Alert slots are separate from capacity, so an incoming incident still gets an agent pod when the normal queue is saturated.