---
title: "Kodema concepts: pipelines, executions and tasks"
description: "Kodema’s model: tenants and projects, pipelines of container and request actions, immutable executions, tasks, the role inbox, roles and Git access rules."
canonical_url: https://optimi.com/en/docs/kodema/concepts
md_url: https://optimi.com/en/docs/kodema/concepts.md
language: en
alternates:
  - lang: fr
    url: https://optimi.com/fr/docs/kodema/concepts
    md_url: https://optimi.com/fr/docs/kodema/concepts.md
last_updated: 2026-11-14
---

# Concepts

Kodema has six primary entities, named the same way in YAML, the CLI, the API
and the database:

```text
Tenants
  Projects
    Resource bindings → service-owned repositories and other resources
    Pipelines
      Executions
        Actions → container or request
    Tasks → conversation + selected pipeline + execution history
    Secrets, service accounts
```

**A pipeline is an ordered list of actions; an action runs a container or
requests an answer; an execution runs a pipeline once; a task is a conversation
that starts executions.**

## Tenants and projects

A **tenant** owns an isolated organization. A **project** groups its software,
work, configuration and resources. Every record, credential, log and event
carries that ownership, and knowing an identifier grants no access to it.

`kodema up` creates one tenant, `tenant-local`, and one project,
`project-local`.

## Pipelines

A pipeline has a stable ID, a name that is unique in its project, and YAML. It
is created or updated **only through the API**. Files kept in Git are posted
with `kodactl pipeline apply`; Kodema never discovers or synchronizes pipeline
definitions on push.

A pipeline is a flat, ordered list. There are no conditions, expressions,
parallel actions, dependency graphs, loops or skipped states. Conditional
behavior belongs in your scripts, or in a separately selected pipeline.

## Actions

| | Container action | Request action |
| --- | --- | --- |
| Declares | `image`, `commands`, `env`, `secrets`, `timeout`, `outputs` | `request`, `subject`, `timeout`, `outputs` |
| Does | Runs the commands in the image, in the shared `/workspace` | Waits for an answer from a role or a service; no container runs |
| Succeeds when | The runtime reports exit code zero | The assignee answers `pass` |
| Fails when | A command exits non-zero, or the timeout passes | The assignee answers `fail`, or the timeout passes |

A request names its assignee as `role/<role>`, for the members who currently
hold that role in scope, or `service/<id>`, for one service account. Its
**subject** is the fixed thing being decided: a candidate, an artifact, an
operation. The subject is persisted when the request becomes answerable and
never changes afterwards.

## Executions

An **execution** runs a pipeline once. Admission stores the exact YAML bytes
and their SHA-256 hash, resolves images to immutable digests, and snapshots the
inputs, the declared secret names and, for a task, its conversation. Later
pipeline edits cannot change that snapshot.

The Kernel visits the actions in declaration order, with at most one active
action per execution. Only success permits the next action.

| | States |
| --- | --- |
| Execution | `queued`, `running`, `succeeded`, `failed`, `cancelled` |
| Action | `pending`, `running`, `succeeded`, `failed`, `cancelled` |

- A waiting request keeps its execution `running`.
- A failed action fails the execution and cancels the actions that had not
  started, with the reason `upstream_failed`.
- Terminal outcomes never change. **Rework is a new execution** that starts at
  the first action with a new workspace and a new credential. Nothing is
  resumed or replayed.
- Every action has a finite timeout, from one minute to thirty days. It becomes
  an absolute deadline when the action starts. There is no execution-level
  deadline.

Container actions of one execution share one disposable `/workspace`, used one
after the other. A request runs no container; the action after it finds the
same files.

An execution does not need a task or a repository: `kodactl run` starts one
from an inline YAML file.

## Requests and the role inbox

When a request becomes active, the execution’s credential is revoked and the
request appears in the **inbox** of its assignees. An answer names the exact
execution and action, gives `pass` or `fail`, and may fill the response fields
the request declared in `outputs`.

- **Pass** succeeds the action and the same execution advances.
- **Fail** fails the action and the execution; the answer, its author and its
  time stay inspectable.
- **Timeout** fails them with `timeout` and no answer. Timeout and cancellation
  never imply approval.

An answer cannot be replaced. Changing a decision needs a new execution.

The inbox lists the active requests and the waiting tasks assigned to your
current roles, and the failed tasks if you are an operator. It is a query over
current state, so a request cannot be lost with a missed notification.

## Tasks

A **task** holds a title, a Markdown description and messages, metadata, a
selected pipeline with its inputs, and the history of its executions. Creating
a task starts nothing; starting it admits one execution.

**A task has four states**

![A created task is open. Asking a question makes it waiting, and the assigned reply reopens it. An open task becomes done when its current execution succeeds. An open or waiting task can be cancelled.](/diagrams/kodema/task-lifecycle-en.svg)

*Queued, running and failed are states of the task’s current execution, not of the task. A failed execution leaves the task open for an operator.*

| State | Meaning |
| --- | --- |
| `open` | Work can be started, is executing, or needs operator follow-up after a failure |
| `waiting` | A question is assigned to a role or a service; the previous execution was cancelled |
| `done` | The current execution succeeded while the task was open |
| `cancelled` | The task was explicitly cancelled |

A failure leaves the task open in the operator inbox. An operator can start a
fresh attempt or cancel; the failed history is kept.

### Questions and fresh executions

A declared request is a **planned** wait inside an execution. A **question** is
an unplanned one: a person, or the running execution itself, asks something the
pipeline did not foresee.

1. The asker saves its context somewhere durable (a pushed commit, an artifact
   digest) and asks, naming an assignee and those references.
2. In one transaction Kodema appends the question, marks the task `waiting` and
   cancels the running execution.
3. The assignee replies. Kodema appends the answer, reopens the task and queues
   **one fresh execution** of the selected pipeline, which reads the updated
   conversation from `/kodema/task.json`.

Neither kind of wait keeps a live process. An agent that needs to resume
restores its context from the references in the conversation.

## Outputs and artifacts

Container outputs and request responses are the same thing: up to eight
declared, named UTF-8 string values per action, each at most 4 KiB. Later
actions read the outputs of earlier **succeeded** actions as files.

An **artifact is an output value**, not a Kodema entity. A build publishes
bytes to your registry, then records a digest-pinned reference such as
`registry.example.com/acme/web@sha256:…`. There is no artifact table or
catalog; the registry owns the bytes.

## Identity and roles

People sign in through OAuth/OIDC. Tenant and project memberships compose five
roles:

| Role | Authority |
| --- | --- |
| `admin` | Configuration and membership administration |
| `engineer` | Repositories, pipelines, tasks and execution |
| `reviewer` | Assigned review decisions |
| `operator` | Runtime operations: follow-up, retry, cancel |
| `viewer` | Authorized read access |

**The admin role grants no review authority.** Role changes apply on the next
call.

Two other kinds of principal exist:

- A **service account** is a software principal outside executions, scoped to a
  tenant or a project. It can hold every role except `admin`, and answers only
  the requests assigned to `service/<its id>`.
- An **execution** has its own short-lived credential while one of its
  containers runs. It can edit its task, ask a question, submit its declared
  outputs and publish custom events. It cannot answer requests, reply to
  questions or administer anything.

## Resource bindings and verification

**Kodema owns identity, roles and recorded decisions. Services own resources,
their access rules and enforcement.**

A **resource binding** registers a service-owned resource, such as a Git
repository, with a stable ID, its enforcing service and the operations that
service may verify. Immediately before an effect, the service asks Kodema for
facts: who the actor is, which roles it holds, and whether an earlier request
in the actor’s own execution approved exactly this operation. The service then
decides by its own rules.

## Git access rules

The optional Git service keeps its rules, in the spirit of gitolite, in
`conf/git.conf` of the tenant’s `admin` repository. A rule change is a commit:

```text
repo admin
    RW                              = @admin

repo shop/web
    R                               = @all
    RW+  refs/heads/work/           = @engineer @execution
    RW   refs/heads/main            = @execution
    option approve.refs/heads/main  = reviewer
```

| Permission | Effect |
| --- | --- |
| `R` | Read the repository |
| `RW` | Create or fast-forward a ref |
| `RW+` | Also rewind or delete it |
| `-` | Deny |

Rules apply in order and the first match wins; no match refuses. Principals are
roles (`@admin`, `@engineer`, `@reviewer`, `@operator`, `@viewer`),
`@execution` for running executions, `@all`, or service-account IDs.

`option approve.<ref> = <role>` makes every update of that ref require approval
evidence: a passed `request: role/<role>` in the pushing execution whose
subject holds `operation: git.ref.update`, the repository, and the exact `ref`,
`expected_base` and `candidate`. People and services carry no such evidence, so
they cannot update an approval-guarded ref directly. Integrating work from a
laptop means pushing a work branch and starting an integration pipeline.

## Events

Every domain change and observable runtime activity is published as a scoped
event: task and request changes, execution and action transitions, verified Git
updates, logs. PostgreSQL records them; NATS distributes them. **NATS carries
events, never commands**: every operation goes through the REST or MCP edge,
and executions keep advancing when the broker is down.

Next: **[Writing pipelines](/en/docs/kodema/developer-guide)**.
