Project¶

The Project custom resource is the top-level grouping unit in tatara. One Project maps to a single SCM owner (a GitHub organization, a GitLab group, or a personal account), owns the per-project memory stack, and drives all scheduled activity: issue scans, MR reviews, brainstorm cycles, health checks, and incident handling.

Every Repository CR must reference a Project. Every Task is born inside a Project.

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

Spec¶

Top-level fields¶

AgentSpec¶

Controls every agent pod spawned by this project.

LifecycleHooks¶

Each field is a shell command string passed to sh -c. An empty field is skipped. Hook failures are logged and counted as metrics but never abort the agent session.

MemorySpec¶

Governs the per-project memory stack: a CNPG-managed Postgres cluster (LightRAG backing store) and a Neo4j single-node instance (graph traversal).

GrafanaSpec¶

Enables an operator-provisioned grafana-mcp sidecar and an alert-webhook receiver for incident-response tasks. The feature is entirely inert when enabled: false.

QueueSpec¶

Fine-grained control over the in-operator admission queue. Omit this section entirely if the defaults derived from maxConcurrentTasks are sufficient.

TokenBudgetSpec¶

Configures the per-Project token-budget admission gate: pauses proactive work (brainstorm, implement, review, ...) at proactivePercent and incident work (the alert pool) at emergencyPercent of the measured usage window. Off by default at every level: the operator-wide default Config is the zero value (enabled: false), and a Project inherits that default verbatim unless it sets its own tokenBudget block - the presence of the block, not any single field, is what turns the gate on for that Project.

ScmSpec¶

Binds the project to an SCM provider and configures the full set of operational knobs: bot identity, approval gates, merge policy, labels, and cron schedules.

Identity¶

Approval gates¶

Merge and review policy¶

Operational tuning¶

Board integration¶

Configure board to enable project-board synchronization.

Cron schedules¶

All cron fields use standard 5-field cron syntax (minute hour dom month dow). An empty schedule disables that activity.

scm.cron.mrScan, scm.cron.issueScan, and scm.cron.cdScan¶

All three activities share the CronActivity shape.

cdScan is the push-CD deploy-supervision backstop: it sweeps Deploying Tasks whose cascade has stalled past 1.5x the applicable deploy budget (deployBudgetSeconds / deploySingleHopBudgetSeconds) with no live watcher, and rerolls them - parks recoverable Tasks, re-implements orphans. It is a peer of mrScan/issueScan, project-scoped. Empty schedule disables it.

scm.cron.brainstorm¶

Opt-in self-driven issue-proposal cycle. Disabled unless enabled: true.

scm.cron.healthCheck¶

Periodic project-health survey. Proposes one targeted discovery issue per cycle via the tatara-health-check skill. Disabled unless enabled: true.

scm.cron.refine¶

Pre-step that fires automatically before each scan and brainstorm cycle. No independent schedule; it is a mandatory barrier, not a standalone cron.

Label set¶

The operator projects a set of SCM labels onto issues to communicate task phase. All labels are configurable; the table shows the defaults.

Status¶

The operator writes observed state back to .status. All fields are read-only.

Top-level status fields¶

Last-run timestamps¶

All timestamps are RFC 3339 and reflect the last time the corresponding activity completed successfully.

TokenBudgetStatus¶

Annotated example¶

apiVersion: tatara.dev/v1alpha1
kind: Project
metadata:
  name: my-platform
  namespace: tatara
spec:
  # (1)!
  scmSecretRef: my-platform-scm-token
  triggerLabel: tatara
  maxConcurrentTasks: 5
  # (10)!
  deployBudgetSeconds: 3300
  deploySingleHopBudgetSeconds: 2100

  agent:
    # (2)!
    model: claude-opus-4-8
    permissionMode: bypassPermissions
    maxTurnsPerTask: 60
    turnTimeoutSeconds: 1800
    contextWindowTokens: 200000
    handoverThresholdPercent: 25
    maxLifecycleIterations: 10
    effort: high
    # (11)!
    maxTaskTokens: 3000000
    modelByKind:
      triageIssue: claude-sonnet-5
      review: claude-sonnet-5
    effortByKind:
      triageIssue: low
      review: medium
    skillsRef: 395713a0ef849fde8df5e27121840e043276eccf
    hooks:
      # (3)!
      postClone: "mise install --quiet"
      conversationFinished: |
        echo "Task ${TATARA_TASK} finished in project ${TATARA_PROJECT}"
    extraEnvs:
      - name: CUSTOM_REGISTRY
        value: harbor.example.com

  memory:
    # (4)!
    pgInstances: 3
    pgStorage: 20Gi
    neo4jStorage: 20Gi

  grafana:
    # (5)!
    enabled: true
    url: https://grafana.example.com
    secretRef: grafana-tatara-credentials

  queue:
    # (6)!
    capacity: 5
    alertCapacity: 2

  # (12)!
  tokenBudget:
    enabled: true
    mode: customWindow
    proactivePercent: 50
    emergencyPercent: 80
    resetSchedule: "0 0 * * *"
    windowDuration: "24h"
    tokenLimit: 50000000

  scm:
    provider: github
    owner: my-org
    # (7)!
    botLogin: my-org-bot
    botEmail: my-org-bot@users.noreply.github.com
    # (8)!
    maintainerLogins:
      - alice
      - bob
    reporterLogins:
      - alice
      - bob
      - charlie
    mergePolicy: afterApproval
    prReactionScope: labeledOrMentioned
    guidance: |
      This project runs the platform team's infrastructure repos.
      Prefer Kubernetes-native approaches. Avoid new external dependencies.

    board:
      githubProjectNumber: 42
      statusField: Status

    cron:
      mrScan:
        # (9)!
        schedule: "*/15 * * * *"
        maxPerRepo: 1
      issueScan:
        schedule: "0 * * * *"
        maxPerRepo: 1
      # (13)!
      cdScan:
        schedule: "*/30 * * * *"
        maxPerRepo: 1
      brainstorm:
        enabled: true
        schedule: "0 9 * * 1"
        maxOpenProposals: 8
        # (14)!
        staleProposalDays: 14
        sources:
          - memory
          - docs
      healthCheck:
        enabled: true
        schedule: "0 10 * * 1"
        maxOpenProposals: 8
        sources:
          - memory
      refine:
        closedLookbackDays: 14

1. scmSecretRef is the only required field. The Secret must exist in the same namespace and contain a token key with the bot PAT.
2. Agent defaults are production-ready out of the box. Override model and image to pin specific versions.
3. Hooks run via sh -c. A non-zero exit is logged and counted but never aborts the session.
4. Set pgInstances: 3 for HA. A single instance is acceptable for non-critical projects but is vulnerable to crash-recovery wedges on CephFS-backed storage.
5. Grafana integration provisions a grafana-mcp sidecar for incident-response tasks. The secretRef Secret must contain serviceAccountToken and webhookSecret keys.
6. capacity overrides the maxConcurrentTasks default for queue admission. alertCapacity reserves dedicated slots so incident tasks are never starved by a backlog of normal tasks.
7. botLogin must match the SCM account whose token is in scmSecretRef. Mismatches cause the operator to misidentify its own comments as human input.
8. maintainerLogins + reporterLogins form the security perimeter. At minimum set maintainerLogins to restrict who can approve proposals.
9. MR scan every 15 minutes, issue scan hourly, brainstorm and health check weekly on Monday morning.
10. Deploy budgets bound how long a Deploying-phase Task can wait for its push-CD cascade to reach a tatara-helmfile apply before parking recoverable. deployBudgetSeconds covers the longest 2-hop path (e.g. cli -> wrapper -> helmfile); deploySingleHopBudgetSeconds is tighter for single-hop artifacts (operator, memory, ingester, chat).
11. maxTaskTokens is a runaway backstop for the turn-uncapped implement/issueLifecycle kinds, not a cost lever. modelByKind/effortByKind tier specific kinds down (here triageIssue/review drop to Sonnet at lower effort) while the project-wide model/effort fallback stays high-end for everything else. skillsRef pins the agent-skills clone to a SHA to avoid main drift.
12. tokenBudget is off unless this block is present with enabled: true. customWindow mode meters absolute tokens against tokenLimit inside the cron-anchored resetSchedule/windowDuration window; claudeSubscription mode gates on wrapper-reported Claude usage percentages instead (see TokenBudgetSpec).
13. cdScan is the push-CD deploy-supervision backstop: it sweeps stalled Deploying Tasks past 1.5x the deploy budget and rerolls them. Empty schedule disables it.
14. staleProposalDays: 14 opts in the brainstorm staleness reaper: bot proposals with no human engagement for 14+ days are auto-closed, keeping the maxOpenProposals backlog from clogging with dead proposals. Omit or set <=0 to keep the reaper off.