---
title: "Writing Kodema pipelines: YAML reference and recipes"
description: "Author Kodema pipelines: YAML fields, files and variables a container sees, outputs, secrets, approval requests, push triggers, and recipes for CI and agents."
canonical_url: https://optimi.com/en/docs/kodema/developer-guide
md_url: https://optimi.com/en/docs/kodema/developer-guide.md
language: en
alternates:
  - lang: fr
    url: https://optimi.com/fr/docs/kodema/guide-developpeur
    md_url: https://optimi.com/fr/docs/kodema/guide-developpeur.md
last_updated: 2026-11-14
---

# Writing pipelines

A pipeline is one YAML document: optional inputs and environment, then an
ordered list of actions. This page is the reference for that document and for
what a container sees when it runs. Try the examples on the local installation
from the **[quickstart](/en/docs/kodema/getting-started)**.

## A pipeline at a glance

```yaml
inputs: [repository, target_ref, expected_base]   # values supplied at start
env:
  LOG_LEVEL: info                                  # literals, for every action
actions:
  - name: implement                                # a container action
    image: registry.example.com/coding-agent:1
    timeout: 2h
    outputs: [candidate]
    commands:
      - implement-and-push

  - name: test
    image: registry.example.com/test-tools:1
    env:
      APP_ENV: test                                # overrides the pipeline value
    commands:
      - test-candidate "$(cat /kodema/outputs/implement/candidate)"

  - name: review                                   # a request action
    request: role/reviewer
    timeout: 72h
    subject:
      operation: git.ref.update
      resource: {from: inputs.repository}
      ref: {from: inputs.target_ref}
      candidate: {from: implement.outputs.candidate}
      expected_base: {from: inputs.expected_base}

  - name: integrate
    image: registry.example.com/git-tools:1
    commands:
      - integrate-candidate "$(cat /kodema/outputs/implement/candidate)"
```

The images and the commands are tools your project supplies. The actions run in
this order, one at a time, in one execution and one workspace. `review` waits
without a container; a pass lets `integrate` run.

## Field reference

**Pipeline**

| Field | Meaning |
| --- | --- |
| `inputs` | Names of the string values supplied when an execution starts |
| `env` | Literal environment variables for every container action |
| `actions` | The ordered, non-empty list of actions |
| `repository`, `service`, `on.push` | Optional push trigger; see [Start on a push](#start-on-a-push) |

**Container action**

| Field | Meaning |
| --- | --- |
| `name` | Unique name in the pipeline; it becomes `KODEMA_ACTION` and a path segment |
| `image` | The image to run, pinned by digest or resolved to one at admission |
| `commands` | Shell commands, run in order; the first failure stops the action |
| `env` | Literal variables; an action value overrides the pipeline value |
| `secrets` | Names of stored secrets to mount as files |
| `timeout` | A duration such as `2m`, `1h` or `72h`, from one minute to thirty days |
| `outputs` | Names of the values this action may submit |

**Request action**

| Field | Meaning |
| --- | --- |
| `name` | Unique name in the pipeline |
| `request` | The assignee: `role/<role>` or `service/<id>` |
| `subject` | What is being decided: literals and direct lookups |
| `timeout` | How long the request stays answerable |
| `outputs` | Names of the response fields the assignee may fill |

An action is one kind or the other: `image` and `request` cannot be combined.
A request has no image, commands, environment or secrets. When `timeout` is
omitted, the installation default applies.

The parser is strict. It refuses unknown or duplicate keys, an empty `actions`
list, two actions with the same name, YAML anchors and aliases, a reference to
an undeclared input, and a reference to a later action.

## Images

Name an image as `host/repository@sha256:…`. A tag (`host/repository:tag`) is
accepted and resolved to a digest through the registry when the execution is
admitted, so a running execution never drifts.

On the local Podman installation the runtime **never pulls an image**: pull it
first with `podman pull`. An image that is missing fails the execution when it
starts, with a message that names the image.

## What a container sees

Kodema replaces the image’s entrypoint with a fail-fast script built from
`commands`, using the image’s own shell and tools. Nothing else is injected: no
runner, no command tracing. Exit code zero succeeds the action; anything else
fails it.

**Environment variables**

| Variable | Value |
| --- | --- |
| `KODEMA_URL` | HTTPS base URL of the Kodema API, reachable from the workload |
| `KODEMA_EXECUTION` | The execution ID |
| `KODEMA_ACTION` | The name of the current action |
| `KODEMA_TASK` | The task ID; unset when the execution has no task |
| `KODEMA_CA_FILE` | `/kodema/ca.crt` when the Podman runtime mounts the installation CA |
| `KODEMA_LLM_ANTHROPIC_BASE_URL`, `KODEMA_LLM_OPENAI_BASE_URL` | The model proxy endpoints, when the installation configures models |

A pipeline cannot declare or override the `KODEMA_*` context variables.

**Files**

| Path | Content |
| --- | --- |
| `/workspace` | Writable directory shared by the container actions of the execution |
| `/kodema/inputs/<key>` | The inputs the execution started with |
| `/kodema/outputs/<action>/<key>` | The outputs of earlier succeeded actions |
| `/kodema/task.json` | The task conversation at admission, a JSON array of messages; absent without a task |
| `/kodema/secrets/<NAME>` | The declared secrets |
| `/kodema/secrets/KODEMA_TOKEN` | The execution credential |

Everything under `/kodema` is read-only and fixed for the duration of the
action, except `KODEMA_TOKEN`, which Kodema renews during a long action. Read
the token file each time you authenticate; do not copy it into a variable at
the start of a long script.

## Pass data between actions

Files are the simplest channel: everything written to `/workspace` is there for
the next container action, also after a request.

**Inputs** are strings supplied at start, with `--input key=value`, and read
from `/kodema/inputs/<key>`.

**Outputs** are small named values that Kodema records: a commit, an image
digest, a verdict. They are the only values a request `subject` can look up,
and they appear in the execution record. An action declares up to eight
outputs, each at most 4 KiB, and submits them over HTTP while it runs:

```text
PUT /api/v1/executions/{execution}/actions/{action}/outputs
```

The call takes the action’s ID and the execution’s current version, which the
container reads from the execution. This helper does it with `curl` and `jq`;
put it in your image:

```sh
#!/bin/sh
# kodema-output: submit the declared outputs of the current action.
# usage: kodema-output '{"image":"registry.example.com/acme/web@sha256:…"}'
set -eu
api="$KODEMA_URL/api/v1/executions/$KODEMA_EXECUTION"

call() {
  curl --silent --show-error ${KODEMA_CA_FILE:+--cacert "$KODEMA_CA_FILE"} \
    --header "Authorization: Bearer $(cat /kodema/secrets/KODEMA_TOKEN)" \
    --header "Content-Type: application/json" "$@"
}

for attempt in 1 2 3 4 5 6 7 8 9 10; do
  view="$(call --fail "$api")"
  action="$(printf '%s' "$view" | jq -r --arg name "$KODEMA_ACTION" \
    '.body.actions[] | select(.name == $name) | .action_id')"
  body="$(printf '%s' "$view" | jq -c --argjson outputs "$1" \
    --arg key "outputs:$KODEMA_EXECUTION:$action" \
    '{input: {outputs: $outputs}, expected_version: .body.version, idempotency_key: $key}')"
  status="$(call --request PUT --data-binary "$body" \
    --output /dev/null --write-out '%{http_code}' "$api/actions/$action/outputs")"
  [ "$status" = 200 ] && exit 0
  [ "$status" = 409 ] || exit 1     # 409 is version_conflict: read again and retry
  sleep 1
done
exit 1
```

A running execution’s version advances as Kodema records observations, so a
`version_conflict` is expected now and then: read the execution again and retry
with the same input and the same idempotency key.

Submitted values stay staged until the runtime confirms that the action
succeeded. A failed or cancelled action discards them. Retrying the same values
converges; replacing them with different values is refused.

## Secrets

Declare the names an action needs; Kodema mounts their current values as files:

```yaml
actions:
  - name: test
    image: registry.example.com/test-tools:1
    secrets: [TEST_DB_PASSWORD]
    commands:
      - export DB_PASSWORD="$(cat /kodema/secrets/TEST_DB_PASSWORD)"
      - run-tests
```

Secrets are stored encrypted per tenant or per project; a project secret
overrides a tenant secret of the same name. An administrator writes them
through the `secret.write` operation, and reads return metadata only. A
missing or denied secret fails the action before it starts. The name
`KODEMA_TOKEN` is reserved.

**In 0.2.1** the installations that ship (`kodema up`, the Podman bundle and
the Helm chart) leave the workload secret allow-list empty, so an action that
declares `secrets:` is refused when it starts, with `forbidden: secret name is
not authorized`. Until that is configurable, a workload has the execution
credential only. Model provider keys are not affected: they stay in the
server, behind the [model proxy](#run-a-coding-agent).

## Requests and approvals

```yaml
  - name: review
    request: role/reviewer
    timeout: 72h
    subject:
      operation: git.ref.update
      resource: {from: inputs.repository}
      candidate: {from: build.outputs.candidate}
    outputs: [comment]
```

- **`request`** is `role/<role>` for the people who hold that role now, or
  `service/<id>` for one service account.
- **`subject`** holds literals and direct lookups only: `{from: inputs.<key>}`
  or `{from: <action>.outputs.<key>}`, where the action is an earlier one.
  There are no expressions or templates. If a looked-up output was never
  submitted, the request fails before it becomes answerable.
- **`outputs`** declares the response fields. A passed request’s responses are
  read by later actions at `/kodema/outputs/<request-name>/<key>`.

A reviewer answers from the inbox:

```sh
kodactl inbox
kodactl approve <execution-id> --output comment="ship it"
kodactl reject <execution-id> --reason "tests do not cover the new path"
```

When a request guards an effect on a service-owned resource, put `operation`
and `resource` in the subject, with the parameters of the effect. The service
that enforces the resource matches them exactly: for a protected Git branch,
`operation: git.ref.update`, the repository’s resource ID, and the exact `ref`,
`expected_base` and `candidate`. The other subject fields are display context
for the reviewer.

## Start on a push

A stored pipeline can start for each accepted push to a repository served by
the Git service:

```yaml
repository: git-web            # the resource ID of the registered repository
service: web-ci                # the service account that starts the execution
on:
  push:
    - refs/heads/work/         # a prefix, because it ends in /
    - refs/heads/release       # an exact ref
inputs: [repository, ref, commit, previous_commit]
actions:
  - name: test
    image: registry.example.com/test-tools:1
    commands:
      - test-commit "$(cat /kodema/inputs/commit)"
```

- Refs match exactly, or by prefix when they end in `/`. Globs and regular
  expressions are refused.
- The only inputs a push supplies are `repository`, `ref`, `commit` and
  `previous_commit`. The pipeline may declare no other input.
- Ref deletions start nothing. Neither does a push made by an execution, so
  pipelines cannot chain themselves through pushes.
- Applying such a pipeline needs pipeline-management authority and `admin`
  authority to bind the service account. Disabling the service account stops
  the trigger.

## Recipes

The digests below are illustrative. Replace the images with yours.

### Test every push

The Git service accepts the execution credential as the password of the user
`kodema`. `inputs.repository` is the resource ID, not the path in the Git URL.

```yaml
repository: git-web
service: web-ci
on:
  push:
    - refs/heads/work/
inputs: [repository, ref, commit, previous_commit]
actions:
  - name: checkout
    image: docker.io/library/buildpack-deps@sha256:712f969c9d81a35f9f00cce701faae521891d42a20b592b61bd0e6c5328fad7c
    timeout: 10m
    env:
      GIT_URL: https://git.example.com/web
    commands:
      - |
        commit="$(cat /kodema/inputs/commit)"
        auth="Authorization: Basic $(printf 'kodema:%s' "$(cat /kodema/secrets/KODEMA_TOKEN)" | base64 -w0)"
        export GIT_TERMINAL_PROMPT=0 KODEMA_GIT_AUTH="$auth"
        git ${KODEMA_CA_FILE:+-c http.sslCAInfo="$KODEMA_CA_FILE"} \
          --config-env=http.extraHeader=KODEMA_GIT_AUTH \
          clone --quiet "$GIT_URL" /workspace/src
        git -C /workspace/src checkout --quiet "$commit"
  - name: test
    image: registry.example.com/acme/ci@sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
    timeout: 20m
    commands:
      - cd /workspace/src && make test
```

The header reaches Git through an environment variable, so the token is never
written to the repository configuration or to a URL.

### Build once, promote the same digest

Keep building and promoting in separate pipelines, so a promotion can be
retried, or rolled back to an older digest, without rebuilding.

```yaml
# build.yaml
actions:
  - name: build
    image: registry.example.com/kodema/build@sha256:44575cf5b28512d75644bf54a517dcef304ff809fd511747621b4d64f19aac66
    outputs: [image]
    commands:
      - build-image          # pushes to your registry, then submits the digest as `image`
```

```yaml
# promote.yaml
inputs: [image]
actions:
  - name: release
    image: registry.example.com/kodema/release@sha256:a4d451ec23463726f72c43d64c710968f6b602cd653b4de8adee1b556240a829
    outputs: [candidate, expected_base]
    commands:
      - write-deploy-candidate     # commits the digest on a work branch of the deploy repository
  - name: approve
    request: role/reviewer
    subject:
      operation: git.ref.update
      resource: deploy-repo-1
      ref: refs/heads/deploy
      expected_base: {from: release.outputs.expected_base}
      candidate: {from: release.outputs.candidate}
    outputs: [approved]
  - name: integrate
    image: registry.example.com/kodema/integrate@sha256:ad9b338ab555c072a2131a946e8ed993cfcee4fe61c1f65efa37a1ce78ecfed5
    commands:
      - integrate-protected-update # fast-forwards the protected ref
```

```sh
kodactl run build.yaml
kodactl run promote.yaml --input image=registry.example.com/acme/web@sha256:…
```

A rollback is the same promotion with an older digest. A recorded output proves
which execution submitted it, not that the deployment is healthy: let a later
action, or your GitOps controller, verify the rollout.

### Run a coding agent

External harnesses such as Claude Code, Codex, OpenCode or Pi run as ordinary
container commands. Provider keys are never mounted: the harness talks to
Kodema’s streaming model proxy and authenticates with the execution
credential.

```yaml
actions:
  - name: harness
    image: registry.example.com/kodema/harness@sha256:49f756463ad9dcfb9b6ade54d7d6f15476e7214f46a65b4b0c55d46845b12f70
    timeout: 2h
    commands:
      - |
        export ANTHROPIC_BASE_URL="${KODEMA_LLM_ANTHROPIC_BASE_URL:-${KODEMA_URL}/llm/anthropic}"
        export OPENAI_BASE_URL="${KODEMA_LLM_OPENAI_BASE_URL:-${KODEMA_URL}/llm/openai/v1}"
        # The credential file has no trailing newline, so read assigns it and reports EOF.
        IFS= read -r ANTHROPIC_API_KEY < /kodema/secrets/KODEMA_TOKEN || [ -n "$ANTHROPIC_API_KEY" ]
        IFS= read -r OPENAI_API_KEY < /kodema/secrets/KODEMA_TOKEN || [ -n "$OPENAI_API_KEY" ]
        export ANTHROPIC_API_KEY OPENAI_API_KEY
        if [ -n "${KODEMA_CA_FILE:-}" ]; then
          export NODE_EXTRA_CA_CERTS="${KODEMA_CA_FILE}" SSL_CERT_FILE="${KODEMA_CA_FILE}"
        fi
        harness run --config harness.yaml
```

The proxy accepts the provider’s native protocol (`/llm/anthropic/v1/messages`,
`/llm/openai/v1/responses`, `/llm/openai/v1/chat/completions`), streams the
response, and stops the stream when the execution is cancelled or the action
reaches its deadline. An operator enables it by giving the server a models file
(`KODEMA_MODELS_FILE`); `kodema up` and the Podman bundle do not set one.

### Ask a question from a pipeline

When an agent needs an answer nobody planned for, it saves its context, asks,
and lets Kodema start a fresh execution after the reply. This works only in an
execution started from a task, and the image needs `kodactl`:

```yaml
inputs: [commit]
actions:
  - name: persist
    image: registry.example.com/kodema/handoff@sha256:283b837d6ffdf6c792a33e6bbf622bd14a1bb81292488a90873b5408da745448
    outputs: [context_commit]
    commands:
      - push-handoff-context "$(cat /kodema/inputs/commit)"
  - name: ask
    image: registry.example.com/kodema/handoff@sha256:283b837d6ffdf6c792a33e6bbf622bd14a1bb81292488a90873b5408da745448
    commands:
      - |
        task_version="$(KODEMA_OUTPUT=json kodactl call task.read \
          --input="$(printf '{"task_id":"%s"}' "$KODEMA_TASK")" \
          | sed -n 's/.*"lifecycle_version":\([0-9][0-9]*\).*/\1/p')"
        kodactl call task.ask \
          --input="$(printf '{"task_id":"%s","question":"Which database should the migration target?","assignment":"role/engineer","references":["commit=%s"]}' \
            "$KODEMA_TASK" "$(cat /kodema/outputs/persist/context_commit)")" \
          --expected-version="$task_version" \
          --idempotency-key="ask:${KODEMA_TASK}:$(cat /kodema/outputs/persist/context_commit)"
```

The ask cancels this execution, so nothing after it may rely on the workspace.
The reply (`kodactl task reply <task-id> --answer "…"`) queues a new execution
whose `/kodema/task.json` contains the question, the answer and the references.

## Run, store and observe

```sh
kodactl run pipeline.yaml --input key=value      # inline, nothing stored, follows to the end
kodactl pipeline apply .kodema/                  # store every .yaml/.yml file of a directory
kodactl task run --title "Fix the login bug" --pipeline <pipeline-id> --input key=value

kodactl inspect <execution-id>                   # actions, states, outputs, decisions
kodactl watch <execution-id>                     # wait for the end; exit 0 on success
kodactl logs <execution-id> --action test        # retained output of one action
```

Retained logs are collected when an action’s workload ends. The
**[CLI reference](/en/docs/kodema/cli)** lists every command.

## Common refusals

| Message or symptom | Cause |
| --- | --- |
| `invalid_input` when applying or starting | Unknown field, duplicate action name, `image` with `request`, YAML alias, forward or undeclared reference |
| `invalid_input` naming an image | The server cannot read the image reference or resolve the tag |
| The execution fails at start, naming an image | The image is not in the local Podman store |
| A `KODEMA_*` variable in `env` is refused | The context variables are reserved |
| `forbidden: secret name is not authorized` | The action declares `secrets:`; see [Secrets](#secrets) |
| A request fails before anyone can answer | A `{from: …}` lookup names an output that was not submitted |
| `on.push` with `refs/heads/*` is refused | Use an exact ref or a prefix ending in `/` |
| `version_conflict` on an output submission | Read the execution again and retry with the same idempotency key |
