Your First Project¶

A Project CR is the top-level entity in tatara. One Project per logical SCM namespace (GitHub organization or GitLab group): it binds the bot identity, SCM connection, agent execution policy, and the per-project memory stack. Creating a Project triggers the operator to provision everything downstream - memory, webhooks, cron schedules, and optionally Grafana incident integration.

1. Minimal Project¶

The minimum viable Project requires only the bot credentials and SCM binding. All other fields have enforced defaults.

apiVersion: tatara.dev/v1alpha1
kind: Project
metadata:
  name: my-project
  namespace: tatara
spec:
  scmSecretRef: tatara-scm   # Secret in the same namespace; key "token" = bot PAT
  triggerLabel: tatara        # label that activates the agent loop on issues (default: tatara)
  maxConcurrentTasks: 3       # max simultaneous agent pods project-wide (default: 3)

  scm:
    provider: github          # github | gitlab
    owner: my-org             # GitHub org name or GitLab group path
    botLogin: my-org-bot      # bot account username on the SCM provider

  agent:
    model: claude-opus-4-8    # Claude model; no built-in default, set it explicitly
    image: harbor.example.com/tatara-claude-code-wrapper:v1.2.3
    effort: xhigh             # reasoning effort: low | medium | high | xhigh | max

SCM Secret format¶

Create the Secret before or alongside the Project:

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.

Required and key top-level fields¶

2. Memory sizing¶

Each Project gets a dedicated memory stack: a CNPG PostgreSQL cluster, a Neo4j graph database, a LightRAG graph indexer, and the tatara-memory API server that other components query. This 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 / replica)"]
    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 enrollments unblocked"]

Configure storage under spec.memory:

Scaling guidance:

• Development / single repository: defaults (pgInstances: 1, pgStorage: 10Gi, neo4jStorage: 10Gi) are sufficient for evaluation.
• Production / multiple repositories: set pgInstances: 3 for PostgreSQL HA and increase storage to 20Gi+ once ingestion consistently hits 80% capacity. The live tatara self-hosting project runs pgInstances: 3, pgStorage: 10Gi, neo4jStorage: 10Gi across eight repositories.
• Large monorepos (>500k LOC): start at neo4jStorage: 20Gi and pgStorage: 20Gi.

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

3. Agent configuration¶

spec.agent configures every agent pod the operator schedules for this Project.

spec:
  agent:
    model: claude-opus-4-8
    image: harbor.example.com/tatara-claude-code-wrapper:v1.2.3
    effort: xhigh
    maxTurnsPerTask: 100
    turnTimeoutSeconds: 1800    # 30 minutes of inactivity, not wall-clock age
    contextWindowTokens: 200000
    handoverThresholdPercent: 25

Lifecycle hooks¶

Optional shell commands the wrapper runs at fixed lifecycle points. Each is executed via sh -c; a non-zero exit is logged 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"

4. Approval and intake¶

Tatara's intake model determines which humans can drive the agent loop and whose comments count as approvals. Configure these fields to close the prompt-injection surface: without explicit allow-lists, any user who can comment on an issue can influence agent behavior.

Allow-lists¶

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

Both lists are overridable per-repository via RepositorySpec.maintainerLogins and RepositorySpec.reporterLogins.

Label set¶

The operator uses six labels to track an issue through its lifecycle. Defaults work out of the box; override only to match organizational naming conventions.

Merge policy¶

spec.scm.mergePolicy controls when the operator merges an agent-opened PR:

• afterApproval (default): merge after a maintainer approves the PR in the SCM review UI.
• autoMergeOnGreenCI: merge automatically once CI passes, without a human approval step. Use only in trusted, low-risk repositories.

PR reaction scope¶

spec.scm.prReactionScope gates which human PRs/MRs the cron mrScan re-review path reacts to. It has no default, and unset is the widest setting, not the narrowest:

• unset / all (the effective default): the mrScan path reviews every open human PR/MR in every enrolled repository. This is the historical open behavior.
• labeledOrMentioned: restricts mrScan re-review to PRs labeled with triggerLabel or that @mention the bot account, so unlabeled, un-mentioned PRs are not re-reviewed every scan cycle.

5. Optional: cron activities, Grafana, and board projection¶

Cron activities¶

Cron drives the autonomous loop. All schedules use standard 5-field cron syntax. An empty schedule disables that activity.

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

spec:
  scm:
    cron:
      brainstorm:
        enabled: true
        schedule: "0 * * * *"
        maxOpenProposals: 8      # skip cycle if open proposals >= this value project-wide
        sources:                 # docs | memory | internet
          - docs
          - memory
          - internet

spec:
  scm:
    cron:
      healthCheck:
        enabled: true
        schedule: "0 2 * * *"   # nightly at 02:00
        maxOpenProposals: 5
        sources:
          - docs
          - memory

Grafana incident-response integration¶

When enabled, the operator provisions a per-project grafana-mcp Deployment (read-only Grafana Viewer service account) and exposes an alert-webhook receiver at <webhookURL>/grafana. Agent pods reach it 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 co-located in each agent pod. Grafana alert rules that POST to the webhook receiver trigger automatic 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   # GitHub Projects v2 (or classic) project number
      statusField: Status       # board field tatara writes to (default: "Status")

For GitLab, use gitlabBoardId instead of githubProjectNumber.

Project guidance¶

spec.scm.guidance is free-form text appended verbatim to brainstorm and health-check prompts. Use it to scope 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.

6. Apply and watch¶

Apply the Project (via tatara-helmfile in production, or directly in a development cluster):

kubectl apply -f my-project.yaml

Watch the memory stack come up:

kubectl -n tatara get project my-project -w \
  -o jsonpath='{.status.memory.phase}{"\n"}'

Wait for phase to become Ready. The operator sets this once the CNPG cluster, Neo4j, LightRAG, and the memory API server are all healthy. Repository enrollments are blocked until status.memory.phase == Ready.

kubectl -n tatara describe project my-project
# look for the MemoryReady condition
kubectl -n tatara get pods -l tatara.dev/project=my-project

Once Ready, grab the webhook URL:

kubectl -n tatara get project my-project \
  -o jsonpath='{.status.webhookURL}'

Register this URL in your SCM provider (GitHub: organization Settings -> Webhooks; GitLab: group Settings -> Webhooks):

Tail structured operator logs to confirm reconciliation is healthy:

kubectl -n tatara logs deploy/tatara-operator -f | jq .

Look for "msg":"project reconciled" or "msg":"memory stack ready" with your project name in the resource_id field.

Annotated full Project YAML¶

A production-ready example for a GitHub organization with all commonly used 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
80

apiVersion: tatara.dev/v1alpha1
kind: Project
metadata:
  name: my-project              # (1)!
  namespace: tatara
spec:
  scmSecretRef: tatara-scm      # (2)!
  triggerLabel: tatara          # (3)!
  maxConcurrentTasks: 5         # (4)!

  agent:
    model: claude-opus-4-8      # (5)!
    image: harbor.example.com/tatara-claude-code-wrapper:v1.2.3  # (6)!
    effort: xhigh               # (7)!
    maxTurnsPerTask: 100        # (8)!
    turnTimeoutSeconds: 1800    # (9)!
    contextWindowTokens: 200000 # (10)!
    handoverThresholdPercent: 25 # (11)!
    maxLifecycleIterations: 10  # (12)!

  memory:
    pgInstances: 3              # (13)!
    pgStorage: 20Gi             # (14)!
    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
    approvedLabel: tatara-approved            # (22)!
    brainstormingLabel: tatara-brainstorming
    implementationLabel: tatara-implementation
    declinedLabel: tatara-declined
    incidentLabel: tatara-incident
    mergePolicy: afterApproval  # (23)!
    prReactionScope: labeledOrMentioned  # (24)!
    babysitDeadlineMinutes: 60  # (25)!
    conversationIdleMinutes: 60 # (26)!
    guidance: >-                # (27)!
      Focus on reliability and observability alongside new features.
    cron:
      issueScan:
        schedule: "0 * * * *"
        maxPerRepo: 1           # (28)!
      mrScan:
        schedule: "0 * * * *"
        maxPerRepo: 1
      brainstorm:
        enabled: true
        schedule: "0 * * * *"
        maxOpenProposals: 8     # (29)!
        sources:
          - docs
          - memory
          - internet
      healthCheck:
        enabled: true
        schedule: "0 2 * * *"
        maxOpenProposals: 5
        sources:
          - docs
          - memory
      refine:
        closedLookbackDays: 30  # (30)!

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

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

1. Project name must be unique per namespace. It becomes the label tatara.dev/project on all downstream resources (agent pods, memory stack, cron jobs).
2. Name of the Kubernetes Secret in the same namespace; must contain key token with the bot PAT. The Secret must exist before the Project is applied.
3. Issues labeled with this value activate the agent loop. Defaults to tatara. Match this to the label you apply in your SCM provider to request agent attention.
4. Maximum concurrent agent pods across all repositories in this Project. Events exceeding this cap wait in Queued state; the queue admits them as slots free.
5. Claude model for all agents in this Project. A single model serves all task types. Changing this affects new tasks immediately; in-flight tasks continue with the model they started on.
6. Full image reference for the tatara-claude-code-wrapper container. Pin to an explicit digest or tag; the operator uses this verbatim in every agent Pod spec.
7. Reasoning effort level. xhigh is the default and the recommended starting point. Lower values reduce API cost but also agent quality on complex multi-file implementation tasks.
8. Maximum agent turns per task. Each turn is one LLM call-response cycle with tool use. A task that reaches this limit hands over to a fresh pod that continues from a compacted summary or full transcript.
9. Per-turn inactivity timeout in seconds. Only a stalled turn (no output for this duration) is killed. A turn actively writing files or running tests is never interrupted by this timer.
10. Context window size in tokens reported to the agent. Set to the model's actual published context limit. The wrapper uses this to decide when to compact the conversation.
11. When last-turn input tokens exceed this percentage of contextWindowTokens, the next pod resumes from a compacted handover summary instead of replaying the full transcript. Below the threshold, full transcript replay is used for better task continuity. Default is 25%.
12. Maximum pod start count (lifecycle iterations) before the task is parked. Prevents indefinite restart loops on persistently failing tasks. Minimum allowed value is 3.
13. CNPG PostgreSQL replica count. 1 is fine for development; 3 delivers HA via synchronous replication and is required for production workloads.
14. PVC storage allocated per PostgreSQL replica. Stores embedding vectors; 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 all enrolled repositories.
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 repo contents read/write, issues, pull requests, and org-membership read on all target repositories. No webhook-admin scope: the operator never registers webhooks (you configure them manually, section 6).
19. GitHub noreply commit-author email for the bot. Links agent commits to the bot account in the GitHub web UI. Find this in the bot account's GitHub email settings.
20. Human maintainer logins. When set, only thread comments from these accounts count as the approval go-ahead, and they form the trusted-insider set the operator treats as authoritative for approve/decline decisions on a proposal thread. 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 silently dropped at intake. Closes the primary prompt-injection vector. Overridable per-repository.
22. The six lifecycle labels that the operator applies and sweeps. Defaults work out of the box. Override only to match organizational label naming conventions.
23. afterApproval (default): the PR is merged after a maintainer approves it in the SCM review UI. autoMergeOnGreenCI: merged automatically once CI passes, no human approval required.
24. Cron mrScan re-review scope. This example opts in to the narrow setting. Left unset (or all), the mrScan path re-reviews every open human PR/MR each cycle. labeledOrMentioned restricts scheduled re-review to PRs labeled with triggerLabel or that @mention the bot. The field has no default; set it explicitly to narrow the loop.
25. Minutes after a task is submitted before the operator considers it stalled and re-queues it if no turn has been recorded. Default 60.
26. Minutes of agent conversation inactivity before the operator considers the session idle and may intervene. Default 60.
27. Free-form project charter text appended verbatim to brainstorm and health-check goal prompts. Use this to focus agent attention on your project's priorities and in-scope concerns.
28. Maximum concurrent issue-scan (or MR-scan) Tasks per repository lane. 1 is the safe default; a single scan agent per repo prevents conflicting concurrent scans.
29. Project-wide cap on open, unapproved agent proposals across all repositories. When the count reaches this number, the brainstorm cycle is skipped entirely for that tick.
30. How far back in days closed issues are loaded during the refine pre-step for already-implemented detection. Defaults to 30 days when not set.
31. Enables the per-project Grafana integration: a read-only grafana-mcp Deployment provisioned with a Viewer service account token (agents reach it via the injected TATARA_GRAFANA_MCP_URL, not as a pod sidecar), and an alert-webhook receiver at <webhookURL>/grafana.
32. Kubernetes Secret containing two keys: serviceAccountToken (Grafana Viewer SA token, mounted into the grafana-mcp container) and webhookSecret (bearer token the configured Grafana contact point must present to the webhook).
33. Queue admission capacity - maximum simultaneously admitted normal-class events. Defaults to maxConcurrentTasks when not set. Override only to decouple queue capacity from the concurrency cap.
34. Reserved concurrent slots for alert-class events (Grafana-sourced incidents). Default 1. Alert slots are separate from capacity, ensuring an incoming incident always gets an agent pod even when the normal queue is fully saturated.