---
title: "Concepts de Kodema : pipelines, exécutions et tâches"
description: "Le modèle Kodema : tenants, projets, pipelines d’actions conteneur et de demande, exécutions immuables, tâches, boîte de réception, rôles, règles d’accès Git."
canonical_url: https://optimi.com/fr/docs/kodema/concepts
md_url: https://optimi.com/fr/docs/kodema/concepts.md
language: fr
alternates:
  - lang: en
    url: https://optimi.com/en/docs/kodema/concepts
    md_url: https://optimi.com/en/docs/kodema/concepts.md
last_updated: 2026-11-14
---

# Concepts

Kodema repose sur six entités principales, nommées de la même façon dans le
YAML, le CLI, l’API et la base de données :

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

**Un pipeline est une liste ordonnée d’actions ; une action exécute un
conteneur ou demande une réponse ; une exécution exécute un pipeline une seule
fois ; une tâche est une conversation qui démarre des exécutions.**

## Tenants et projets

Un **tenant** possède une organisation isolée. Un **projet** regroupe ses
logiciels, son travail, sa configuration et ses ressources. Chaque
enregistrement, identifiant, journal et événement porte cette appartenance, et
connaître un ID ne donne aucun accès à l’élément correspondant.

`kodema up` crée un tenant, `tenant-local`, et un projet,
`project-local`.

## Pipelines

Un pipeline a un ID stable, un nom unique dans son projet et un contenu YAML.
Il est créé ou mis à jour **uniquement par l’API**. Les fichiers conservés dans
Git sont envoyés avec `kodactl pipeline apply` ; Kodema ne découvre ni ne
synchronise jamais les définitions de pipeline lors d’un push.

Un pipeline est une liste plate et ordonnée. Il n’y a ni conditions, ni
expressions, ni actions parallèles, ni graphes de dépendances, ni boucles, ni
états ignorés. Un comportement conditionnel a sa place dans vos scripts, ou
dans un pipeline sélectionné séparément.

## Actions

| | Action conteneur | Action de demande |
| --- | --- | --- |
| Déclare | `image`, `commands`, `env`, `secrets`, `timeout`, `outputs` | `request`, `subject`, `timeout`, `outputs` |
| Fait | Exécute les commandes dans l’image, dans le `/workspace` partagé | Attend la réponse d’un rôle ou d’un service ; aucun conteneur ne s’exécute |
| Réussit quand | Le runtime signale un code de sortie zéro | Le destinataire répond `pass` |
| Échoue quand | Une commande se termine avec un code non nul, ou le délai expire | Le destinataire répond `fail`, ou le délai expire |

Une demande désigne son destinataire par `role/<role>`, pour les membres qui
détiennent actuellement ce rôle dans le périmètre, ou par `service/<id>`, pour
un compte de service. Son **sujet** est l’objet précis de la décision : un
candidat, un artefact, une opération. Le sujet est persisté lorsqu’il devient
possible de répondre à la demande et ne change plus ensuite.

## Exécutions

Une **exécution** exécute un pipeline une seule fois. L’admission enregistre
les octets exacts du YAML et leur hachage SHA-256, résout les images en
empreintes immuables et fige les entrées, les noms des secrets déclarés et,
pour une tâche, sa conversation. Les modifications ultérieures du pipeline ne
peuvent pas changer cet instantané.

Le Kernel parcourt les actions dans l’ordre de déclaration, avec au plus une
action active par exécution. Seule une réussite autorise l’action suivante.

| | États |
| --- | --- |
| Exécution | `queued`, `running`, `succeeded`, `failed`, `cancelled` |
| Action | `pending`, `running`, `succeeded`, `failed`, `cancelled` |

- Une demande en attente maintient son exécution à l’état `running`.
- Une action en échec fait échouer l’exécution et annule les actions qui
  n’avaient pas démarré, avec le motif `upstream_failed`.
- Les résultats terminaux ne changent jamais. **Refaire le travail passe par
  une nouvelle exécution**, qui démarre à la première action avec un nouvel
  espace de travail et un nouvel identifiant. Rien n’est repris ni rejoué.
- Chaque action a un délai fini, d’une minute à trente jours. Il devient une
  échéance absolue au démarrage de l’action. Il n’existe pas d’échéance au
  niveau de l’exécution.

Les actions conteneur d’une même exécution partagent un seul `/workspace`
jetable, qu’elles utilisent l’une après l’autre. Une demande n’exécute aucun
conteneur ; l’action qui la suit retrouve les mêmes fichiers.

Une exécution n’a besoin ni d’une tâche ni d’un dépôt : `kodactl run` en
démarre une à partir d’un fichier YAML fourni directement.

## Demandes et boîte de réception par rôle

Lorsqu’une demande devient active, l’identifiant de l’exécution est révoqué et
la demande apparaît dans la **boîte de réception** de ses destinataires. Une
réponse désigne l’exécution et l’action exactes, donne `pass` ou `fail`, et
peut renseigner les champs de réponse que la demande a déclarés dans `outputs`.

- **L’acceptation** fait réussir l’action, et la même exécution avance.
- **Le rejet** fait échouer l’action et l’exécution ; la réponse, son auteur et
  son horodatage restent consultables.
- **L’expiration du délai** les fait échouer avec `timeout` et sans réponse. Ni
  l’expiration du délai ni l’annulation ne valent approbation.

Une réponse ne peut pas être remplacée. Changer une décision exige une nouvelle
exécution.

La boîte de réception liste les demandes actives et les tâches en attente
assignées à vos rôles actuels, ainsi que les tâches en échec si vous êtes
opérateur. C’est une requête sur l’état courant : une demande ne peut donc pas
se perdre à cause d’une notification manquée.

## Tâches

Une **tâche** contient un titre, une description et des messages en Markdown,
des métadonnées, un pipeline sélectionné avec ses entrées, et l’historique de
ses exécutions. Créer une tâche ne démarre rien ; la démarrer admet une
exécution.

**Une tâche a quatre états**

![Une tâche créée est à l’état open. Poser une question la fait passer à waiting, et la réponse du destinataire la rouvre. Une tâche open devient done lorsque son exécution courante réussit. Une tâche open ou waiting peut être annulée.](/diagrams/kodema/task-lifecycle-fr.svg)

*Queued, running et failed sont des états de l’exécution courante de la tâche, pas de la tâche. Une exécution en échec laisse la tâche ouverte pour un opérateur.*

| État | Signification |
| --- | --- |
| `open` | Le travail peut être démarré, est en cours d’exécution, ou nécessite un suivi par un opérateur après un échec |
| `waiting` | Une question est assignée à un rôle ou à un service ; l’exécution précédente a été annulée |
| `done` | L’exécution courante a réussi alors que la tâche était ouverte |
| `cancelled` | La tâche a été explicitement annulée |

Un échec laisse la tâche ouverte dans la boîte de réception des opérateurs. Un
opérateur peut lancer une nouvelle tentative ou annuler ; l’historique de
l’échec est conservé.

### Questions et nouvelles exécutions

Une demande déclarée est une attente **prévue** au sein d’une exécution. Une
**question** est une attente imprévue : une personne, ou l’exécution en cours
elle-même, demande quelque chose que le pipeline n’avait pas prévu.

1. L’auteur de la question enregistre son contexte dans un emplacement durable
   (un commit poussé, une empreinte d’artefact) et pose sa question en
   désignant un destinataire et ces références.
2. En une seule transaction, Kodema ajoute la question, passe la tâche à l’état
   `waiting` et annule l’exécution en cours.
3. Le destinataire répond. Kodema ajoute la réponse, rouvre la tâche et met en
   file d’attente **une nouvelle exécution** du pipeline sélectionné, qui lit
   la conversation mise à jour dans `/kodema/task.json`.

Aucune de ces deux attentes ne conserve de processus actif. Un agent qui doit
reprendre son travail restaure son contexte à partir des références présentes
dans la conversation.

## Sorties et artefacts

Les sorties d’un conteneur et les réponses à une demande sont la même chose :
jusqu’à huit valeurs déclarées et nommées par action, des chaînes UTF-8 de
4 Kio au plus chacune. Les actions suivantes lisent sous forme de fichiers les
sorties des actions précédentes **réussies**.

Un **artefact est une valeur de sortie**, pas une entité Kodema. Un build
publie des octets dans votre registre, puis enregistre une référence épinglée
par empreinte, par exemple `registry.example.com/acme/web@sha256:…`. Il
n’existe ni table ni catalogue d’artefacts ; les octets appartiennent au
registre.

## Identité et rôles

Les personnes se connectent par OAuth/OIDC. Les appartenances aux tenants et
aux projets combinent cinq rôles :

| Rôle | Autorité |
| --- | --- |
| `admin` | Administration de la configuration et des appartenances |
| `engineer` | Dépôts, pipelines, tâches et exécution |
| `reviewer` | Décisions de revue qui lui sont assignées |
| `operator` | Opérations sur l’exécution : suivi, nouvelle tentative, annulation |
| `viewer` | Accès en lecture autorisé |

**Le rôle admin ne confère aucune autorité de revue.** Les changements de rôle
s’appliquent dès l’appel suivant.

Il existe deux autres types de principal :

- Un **compte de service** est un principal logiciel extérieur aux exécutions,
  dont le périmètre est un tenant ou un projet. Il peut détenir tous les rôles
  sauf `admin`, et ne répond qu’aux demandes assignées à `service/<its id>`.
- Une **exécution** dispose de son propre identifiant de courte durée tant que
  l’un de ses conteneurs s’exécute. Elle peut modifier sa tâche, poser une
  question, soumettre ses sorties déclarées et publier des événements
  personnalisés. Elle ne peut ni répondre à des demandes, ni répondre à des
  questions, ni administrer quoi que ce soit.

## Liaisons de ressources et vérification

**L’identité, les rôles et les décisions enregistrées appartiennent à Kodema.
Les ressources, leurs règles d’accès et leur application appartiennent aux
services.**

Une **liaison de ressource** enregistre une ressource appartenant à un service,
par exemple un dépôt Git, avec un ID stable, le service qui en applique les
règles et les opérations que ce service peut vérifier. Juste avant un effet, le
service demande des faits à Kodema : qui est l’acteur, quels rôles il détient,
et si une demande antérieure dans l’exécution même de l’acteur a approuvé
exactement cette opération. Le service décide ensuite selon ses propres règles.

## Règles d’accès Git

Le service Git optionnel conserve ses règles, dans l’esprit de gitolite, dans
le fichier `conf/git.conf` du dépôt `admin` du tenant. Un changement de règle
est un 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 | Effet |
| --- | --- |
| `R` | Lire le dépôt |
| `RW` | Créer une référence ou l’avancer en fast-forward |
| `RW+` | Aussi la faire reculer ou la supprimer |
| `-` | Refuser |

Les règles s’appliquent dans l’ordre et la première correspondance l’emporte ;
sans correspondance, l’accès est refusé. Les principaux sont des rôles
(`@admin`, `@engineer`, `@reviewer`, `@operator`, `@viewer`), `@execution` pour
les exécutions en cours, `@all`, ou des ID de comptes de service.

`option approve.<ref> = <role>` impose une preuve d’approbation pour toute mise
à jour de cette référence : une demande `request: role/<role>` acceptée dans
l’exécution qui pousse, dont le sujet contient `operation: git.ref.update`, le
dépôt, ainsi que les valeurs exactes de `ref`, `expected_base` et `candidate`.
Les personnes et les services ne portent aucune preuve de ce type : ils ne
peuvent donc pas mettre à jour directement une référence protégée par
approbation. Intégrer un travail depuis un ordinateur portable revient à
pousser une branche de travail et à démarrer un pipeline d’intégration.

## Événements

Chaque changement du domaine et chaque activité d’exécution observable est
publié sous forme d’événement rattaché à un périmètre : changements de tâches
et de demandes, transitions d’exécutions et d’actions, mises à jour Git
vérifiées, journaux. PostgreSQL les enregistre ; NATS les distribue. **NATS
transporte des événements, jamais des commandes** : chaque opération passe par
l’interface REST ou MCP, et les exécutions continuent d’avancer lorsque le broker
est indisponible.

Suite : **[Écrire des pipelines](/fr/docs/kodema/guide-developpeur)**.
