---
title: "Écrire des pipelines Kodema : référence YAML et recettes"
description: "Écrire des pipelines Kodema : champs YAML, fichiers et variables d’un conteneur, sorties, secrets, approbations, déclenchement sur push, recettes CI et agents."
canonical_url: https://optimi.com/fr/docs/kodema/guide-developpeur
md_url: https://optimi.com/fr/docs/kodema/guide-developpeur.md
language: fr
alternates:
  - lang: en
    url: https://optimi.com/en/docs/kodema/developer-guide
    md_url: https://optimi.com/en/docs/kodema/developer-guide.md
last_updated: 2026-11-14
---

# Écrire des pipelines

Un pipeline est un seul document YAML : des entrées et un environnement
facultatifs, puis une liste ordonnée d’actions. Cette page est la référence de
ce document et de ce que voit un conteneur lorsqu’il s’exécute. Essayez les
exemples sur l’installation locale du
**[démarrage rapide](/fr/docs/kodema/premiers-pas)**.

## Un pipeline en un coup d’œil

```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)"
```

Les images et les commandes sont des outils fournis par votre projet. Les
actions s’exécutent dans cet ordre, une à la fois, dans une seule exécution et
un seul espace de travail. `review` attend sans conteneur ; une acceptation
permet à `integrate` de s’exécuter.

## Référence des champs

**Pipeline**

| Champ | Signification |
| --- | --- |
| `inputs` | Noms des valeurs de type chaîne fournies au démarrage d’une exécution |
| `env` | Variables d’environnement littérales pour chaque action conteneur |
| `actions` | La liste ordonnée et non vide des actions |
| `repository`, `service`, `on.push` | Déclenchement sur push facultatif ; voir [Démarrer sur un push](#démarrer-sur-un-push) |

**Action conteneur**

| Champ | Signification |
| --- | --- |
| `name` | Nom unique dans le pipeline ; il devient `KODEMA_ACTION` et un segment de chemin |
| `image` | L’image à exécuter, épinglée par empreinte ou résolue en empreinte à l’admission |
| `commands` | Commandes shell, exécutées dans l’ordre ; le premier échec arrête l’action |
| `env` | Variables littérales ; une valeur d’action remplace la valeur du pipeline |
| `secrets` | Noms des secrets stockés à monter sous forme de fichiers |
| `timeout` | Une durée telle que `2m`, `1h` ou `72h`, d’une minute à trente jours |
| `outputs` | Noms des valeurs que cette action peut soumettre |

**Action de demande**

| Champ | Signification |
| --- | --- |
| `name` | Nom unique dans le pipeline |
| `request` | Le destinataire : `role/<role>` ou `service/<id>` |
| `subject` | Ce qui fait l’objet de la décision : littéraux et références directes |
| `timeout` | Durée pendant laquelle on peut répondre à la demande |
| `outputs` | Noms des champs de réponse que le destinataire peut remplir |

Une action est de l’un ou l’autre type : `image` et `request` ne peuvent pas
être combinés. Une demande n’a ni image, ni commandes, ni environnement, ni
secrets. Lorsque `timeout` est omis, la valeur par défaut de l’installation
s’applique.

L’analyseur est strict. Il refuse les clés inconnues ou dupliquées, une liste
`actions` vide, deux actions portant le même nom, les ancres et alias YAML, une
référence à une entrée non déclarée et une référence à une action ultérieure.

## Images

Nommez une image sous la forme `host/repository@sha256:…`. Un tag
(`host/repository:tag`) est accepté et résolu en empreinte auprès du registre
lorsque l’exécution est admise : une exécution en cours ne dérive donc jamais.

Sur l’installation Podman locale, le runtime **ne télécharge jamais d’image** :
téléchargez-la d’abord avec `podman pull`. Une image manquante fait échouer
l’exécution à son démarrage, avec un message qui nomme l’image.

## Ce que voit un conteneur

Kodema remplace le point d’entrée de l’image par un script qui s’arrête au
premier échec, construit à partir de `commands`, et utilise le shell et les
outils de l’image elle-même. Rien d’autre n’est injecté : ni runner, ni traçage
des commandes. Un code de sortie zéro fait réussir l’action ; toute autre
valeur la fait échouer.

**Variables d’environnement**

| Variable | Valeur |
| --- | --- |
| `KODEMA_URL` | URL de base HTTPS de l’API Kodema, joignable depuis la charge de travail |
| `KODEMA_EXECUTION` | L’ID de l’exécution |
| `KODEMA_ACTION` | Le nom de l’action en cours |
| `KODEMA_TASK` | L’ID de la tâche ; non définie lorsque l’exécution n’a pas de tâche |
| `KODEMA_CA_FILE` | `/kodema/ca.crt` lorsque le runtime Podman monte l’autorité de certification de l’installation |
| `KODEMA_LLM_ANTHROPIC_BASE_URL`, `KODEMA_LLM_OPENAI_BASE_URL` | Les points d’accès du proxy de modèles, lorsque l’installation configure des modèles |

Un pipeline ne peut ni déclarer ni remplacer les variables de contexte
`KODEMA_*`.

**Fichiers**

| Chemin | Contenu |
| --- | --- |
| `/workspace` | Répertoire accessible en écriture, partagé par les actions conteneur de l’exécution |
| `/kodema/inputs/<key>` | Les entrées avec lesquelles l’exécution a démarré |
| `/kodema/outputs/<action>/<key>` | Les sorties des actions précédentes réussies |
| `/kodema/task.json` | La conversation de la tâche à l’admission, un tableau JSON de messages ; absent sans tâche |
| `/kodema/secrets/<NAME>` | Les secrets déclarés |
| `/kodema/secrets/KODEMA_TOKEN` | L’identifiant d’exécution |

Tout ce qui se trouve sous `/kodema` est en lecture seule et figé pendant la
durée de l’action, sauf `KODEMA_TOKEN`, que Kodema renouvelle pendant une
action longue. Lisez le fichier du jeton à chaque authentification ; ne le
copiez pas dans une variable au début d’un long script.

## Transmettre des données entre actions

Les fichiers sont le canal le plus simple : tout ce qui est écrit dans
`/workspace` reste disponible pour l’action conteneur suivante, y compris après
une demande.

Les **entrées** sont des chaînes fournies au démarrage, avec
`--input key=value`, et lues depuis `/kodema/inputs/<key>`.

Les **sorties** sont de petites valeurs nommées que Kodema enregistre : un
commit, une empreinte d’image, un verdict. Ce sont les seules valeurs que le
`subject` d’une demande peut référencer, et elles apparaissent dans
l’enregistrement de l’exécution. Une action déclare jusqu’à huit sorties, de
4 Kio au plus chacune, et les soumet par HTTP pendant son exécution :

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

L’appel prend l’ID de l’action et la version courante de l’exécution, que le
conteneur lit dans l’exécution. Ce script utilitaire le fait avec `curl` et
`jq` ; placez-le dans votre 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
```

La version d’une exécution en cours avance à mesure que Kodema enregistre des
observations ; un `version_conflict` est donc attendu de temps en temps :
relisez l’exécution et réessayez avec la même entrée et la même clé
d’idempotence.

Les valeurs soumises restent en attente jusqu’à ce que le runtime confirme que
l’action a réussi. Une action en échec ou annulée les supprime. Soumettre à
nouveau les mêmes valeurs converge ; les remplacer par des valeurs différentes
est refusé.

## Secrets

Déclarez les noms dont une action a besoin ; Kodema monte leurs valeurs
courantes sous forme de fichiers :

```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
```

Les secrets sont stockés chiffrés par tenant ou par projet ; un secret de
projet remplace un secret de tenant du même nom. Un administrateur les écrit
avec l’opération `secret.write`, et les lectures ne renvoient que des
métadonnées. Un secret manquant ou refusé fait échouer l’action avant son
démarrage. Le nom `KODEMA_TOKEN` est réservé.

**Dans la version 0.2.1**, les installations livrées (`kodema up`, le bundle
Podman et le chart Helm) laissent vide la liste d’autorisation des secrets de
charge de travail : une action qui déclare `secrets:` est donc refusée à son
démarrage, avec `forbidden: secret name is not authorized`. Tant que ce n’est
pas configurable, une charge de travail ne dispose que de l’identifiant
d’exécution. Les clés des fournisseurs de modèles ne sont pas concernées :
elles restent dans le serveur, derrière le
[proxy de modèles](#lancer-un-agent-de-code).

## Demandes et approbations

```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`** vaut `role/<role>` pour les personnes qui détiennent ce rôle à
  cet instant, ou `service/<id>` pour un seul compte de service.
- **`subject`** ne contient que des littéraux et des références directes :
  `{from: inputs.<key>}` ou `{from: <action>.outputs.<key>}`, où l’action est
  une action précédente. Il n’y a ni expressions ni modèles. Si une sortie
  référencée n’a jamais été soumise, la demande échoue avant qu’on puisse y
  répondre.
- **`outputs`** déclare les champs de réponse. Les réponses d’une demande
  acceptée sont lues par les actions suivantes dans
  `/kodema/outputs/<request-name>/<key>`.

Un relecteur répond depuis la boîte de réception :

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

Lorsqu’une demande protège un effet sur une ressource détenue par un service,
placez `operation` et `resource` dans le sujet, avec les paramètres de l’effet.
Le service qui contrôle la ressource les compare exactement : pour une branche
Git protégée, `operation: git.ref.update`, l’ID de ressource du dépôt, et les
valeurs exactes de `ref`, `expected_base` et `candidate`. Les autres champs du
sujet servent de contexte d’affichage pour le relecteur.

## Démarrer sur un push

Un pipeline stocké peut démarrer à chaque push accepté vers un dépôt servi par
le service Git :

```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)"
```

- Les refs correspondent exactement, ou par préfixe lorsqu’elles se terminent
  par `/`. Les globs et les expressions régulières sont refusés.
- Les seules entrées fournies par un push sont `repository`, `ref`, `commit` et
  `previous_commit`. Le pipeline ne peut déclarer aucune autre entrée.
- Les suppressions de refs ne démarrent rien. Un push effectué par une
  exécution non plus : les pipelines ne peuvent donc pas s’enchaîner eux-mêmes
  par des push.
- Appliquer un tel pipeline nécessite l’autorité de gestion des pipelines et
  l’autorité `admin` pour lier le compte de service. Désactiver le compte de
  service arrête le déclenchement.

## Recettes

Les empreintes ci-dessous sont données à titre d’illustration. Remplacez les
images par les vôtres.

### Tester chaque push

Le service Git accepte l’identifiant d’exécution comme mot de passe de
l’utilisateur `kodema`. `inputs.repository` est l’ID de ressource, pas le
chemin dans l’URL Git.

```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
```

L’en-tête parvient à Git par une variable d’environnement : le jeton n’est
donc jamais écrit dans la configuration du dépôt ni dans une URL.

### Construire une fois, promouvoir la même empreinte

Gardez la construction et la promotion dans des pipelines séparés : une
promotion peut ainsi être relancée, ou ramenée à une empreinte plus ancienne,
sans reconstruire.

```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:…
```

Un retour arrière est la même promotion avec une empreinte plus ancienne. Une
sortie enregistrée prouve quelle exécution l’a soumise, pas que le déploiement
est sain : laissez une action ultérieure, ou votre contrôleur GitOps, vérifier
le déploiement.

### Lancer un agent de code

Les harness externes tels que Claude Code, Codex, OpenCode ou Pi s’exécutent
comme des commandes de conteneur ordinaires. Les clés des fournisseurs ne sont
jamais montées : le harness dialogue avec le proxy de modèles en streaming de
Kodema et s’authentifie avec l’identifiant d’exécution.

```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
```

Le proxy accepte le protocole natif du fournisseur
(`/llm/anthropic/v1/messages`, `/llm/openai/v1/responses`,
`/llm/openai/v1/chat/completions`), transmet la réponse en flux et interrompt
le flux lorsque l’exécution est annulée ou que l’action atteint son échéance.
Un opérateur l’active en fournissant au serveur un fichier de modèles
(`KODEMA_MODELS_FILE`) ; `kodema up` et le bundle Podman n’en définissent pas.

### Poser une question depuis un pipeline

Lorsqu’un agent a besoin d’une réponse que personne n’avait prévue, il
enregistre son contexte, pose sa question et laisse Kodema démarrer une
nouvelle exécution après la réponse. Cela ne fonctionne que dans une exécution
démarrée depuis une tâche, et l’image doit contenir `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)"
```

La question annule cette exécution : rien de ce qui suit ne peut donc compter
sur l’espace de travail. La réponse
(`kodactl task reply <task-id> --answer "…"`) met en file d’attente une
nouvelle exécution dont le `/kodema/task.json` contient la question, la réponse
et les références.

## Lancer, stocker et observer

```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
```

Les journaux conservés sont collectés lorsque la charge de travail d’une
action se termine. La **[référence CLI](/fr/docs/kodema/cli)** liste toutes les
commandes.

## Refus courants

| Message ou symptôme | Cause |
| --- | --- |
| `invalid_input` à l’application ou au démarrage | Champ inconnu, nom d’action dupliqué, `image` avec `request`, alias YAML, référence anticipée ou non déclarée |
| `invalid_input` nommant une image | Le serveur ne peut pas lire la référence de l’image ni résoudre le tag |
| L’exécution échoue au démarrage, en nommant une image | L’image n’est pas dans le stockage Podman local |
| Une variable `KODEMA_*` dans `env` est refusée | Les variables de contexte sont réservées |
| `forbidden: secret name is not authorized` | L’action déclare `secrets:` ; voir [Secrets](#secrets) |
| Une demande échoue avant que quiconque puisse répondre | Une référence `{from: …}` désigne une sortie qui n’a pas été soumise |
| `on.push` avec `refs/heads/*` est refusé | Utilisez une ref exacte ou un préfixe se terminant par `/` |
| `version_conflict` lors d’une soumission de sortie | Relisez l’exécution et réessayez avec la même clé d’idempotence |
