Ein Akzeptanz-Manifest im Repository anlegen

Das Akzeptanz-Manifest ist eine kleine JSON-Datei in Ihrem Repository. Sie sagt kanman, wie Ihre Anwendung in einer frischen Umgebung startet und wie die Akzeptanzspezifikation einer Story läuft. Damit kann das Outcome-Gate jede Änderung belegen: Die Spec muss vor Beginn der Arbeit fehlschlagen und auf einem frischen Checkout bestehen, bevor der Pull Request mergebar wird.

Ohne Manifest lässt nur das Preset Testphase kanman arbeiten, und jedes Nachweispaket sagt, dass kein Ergebnisnachweis vorliegt.

Für eine typische Webanwendung brauchen Sie etwa 30 Minuten. Die vollständige Referenz aller Schlüssel steht unter .kanman/acceptance.json und .kanman/verify.json.

Für einen schnellen Start öffnet kanman einen Pull Request mit einem Start-Manifest für Ihren Stack: im Probelauf der Team-Einrichtung oder später in den Einstellungen des Teams unter Repositories und Tracker mit Akzeptanz-Manifeste prüfen. Passen Sie es dann mit den folgenden Schritten an.

Was Sie hinzufügen

.kanman/
  acceptance.json        wie die App bereitgestellt und die Spec einer Story ausgeführt wird
  verify.json            Ihr lokaler Prüfbefehl (Lint, Typecheck, Tests)
  acceptance/
    README.md            optional: erklärt Ihrem Team den Ordner
    <KEY>/               ein Ordner pro Story, geschrieben von kanman

Die beiden JSON-Dateien schreiben Sie einmal. Die Specs unter .kanman/acceptance/<KEY>/ schreibt kanman aus dem Demonstrate-Block jeder Story.

Schritt 1: Die App mit einem Befehl starten

kanman braucht einen Weg, Ihre App von Grund auf zu starten, in einer Umgebung, in der sonst nichts läuft. Zwei Möglichkeiten:

Bei Docker Compose legen Sie eine eigene Datei an, zum Beispiel docker-compose.acceptance.yml, mit einem Health-Check, damit kanman weiß, wann die App bereit ist:

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      PORT: "3000"
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://localhost:3000/health').then((r) => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
      interval: 2s
      timeout: 3s
      retries: 30

Legen Sie Testdaten in der Compose-Datei oder beim Start an. Specs müssen gegen die echte App laufen, nie gegen Mocks von ihr.

Schritt 2: .kanman/acceptance.json schreiben

Das ist das Manifest des öffentlichen Demo-Repositorys, das Playwright-Specs gegen eine Fastify-App ausführt:

{
  "version": 1,
  "provision": {
    "type": "docker_compose",
    "file": "docker-compose.acceptance.yml",
    "up": "docker compose -f docker-compose.acceptance.yml up -d --build --wait",
    "down": "docker compose -f docker-compose.acceptance.yml down -v"
  },
  "ready_url": "http://localhost:3000/api/invoices",
  "ready_timeout_seconds": 120,
  "setup": "npm ci && npx playwright install --with-deps chromium",
  "run": {
    "command": "npx playwright test",
    "spec_arg": ".kanman/acceptance/{KEY}/",
    "env": {
      "BASE_URL": "http://localhost:3000"
    }
  },
  "spec_dir": ".kanman/acceptance/{KEY}",
  "artifacts": [
    "test-results/**/trace.zip",
    "test-results/**/*.png",
    "test-results/**/*.webm",
    "test-results/results.json",
    "playwright-report/**"
  ]
}

Was die Teile bewirken:

• provision startet und stoppt die Umgebung.
• ready_url wird abgefragt, bis es antwortet; ready_timeout_seconds ist die maximale Wartezeit.
• setup installiert, was die Specs brauchen.
• run.command plus run.spec_arg führt die Specs einer Story aus. {KEY} wird zum Story-Key, zum Beispiel SBX-12.
• artifacts sind die Dateien, die kanman als Nachweis speichert: Traces, Screenshots, Videos, Berichte. Den einfachen Pfad test-results/results.json liest kanman als JSON-Bericht, daraus stammen die Testzahlen im Nachweispaket.

Schritt 3: .kanman/verify.json schreiben

Das Verify-Manifest ist der Befehl, den eine Entwicklerin vor dem Push ausführt. kanman führt ihn aus, wenn der Coding-Agent fertig ist, vor dem Review und den langsameren Gates, und gibt dem Agenten eine Runde, um zu beheben, was er meldet (siehe .kanman/verify.json). Der Schritt ist optional, findet aber Lint- und Typfehler früh:

{
  "version": 1,
  "cwd": ".",
  "setup": "npm ci",
  "command": "npm run lint && npm run typecheck && npm test",
  "env": {
    "CI": "true"
  },
  "ci_var_keys": []
}

Brauchen Ihre Tests Werte aus der CI (etwa einen Lizenzschlüssel für ein Testwerkzeug), tragen Sie in ci_var_keys nur die Namen ein. Die Werte bleiben in Ihren CI-Einstellungen; kanman liest sie nur für den Prüfbefehl. Secrets, die Ihre CI nicht herausgibt, etwa GitHub-Actions-Secrets, gehören stattdessen unter Secrets für Runs.

Schritt 4: Lokal ausprobieren

Führen Sie aus, was kanman ausführen wird, mit der Beispiel-Spec aus dem Demo-Repository oder einer eigenen:

docker compose -f docker-compose.acceptance.yml up -d --build --wait
npx playwright test .kanman/acceptance/EXAMPLE-1/
docker compose -f docker-compose.acceptance.yml down -v

Funktioniert das auf einem frischen Klon Ihres Repositorys, funktioniert es auch für kanman.

Schritt 5: Den Spec-Ordner schützen

Die Akzeptanzspezifikationen sind der Schiedsrichter, die Umsetzung darf sie also nie ändern. kanman setzt das selbst durch: Executors können nie in .kanman/acceptance/** schreiben, und der Diff-Wächter stoppt einen Run, wenn ein Commit den Ordner berührt. Wir empfehlen trotzdem eine zweite Sicherung in Ihrem Git-Host:

# .github/CODEOWNERS (GitHub) oder CODEOWNERS (GitLab)
/.kanman/ @your-org/tech-leads

Machen Sie außerdem den Commit-Status kanman/outcome-gate in Ihrem Branch-Schutz zum Pflicht-Status. Dann lässt sich ein Pull Request erst mergen, wenn das Outcome-Gate bestanden ist.

Schritt 6: Über einen Pull Request committen

Fügen Sie die Dateien in einem normalen Pull Request hinzu und mergen Sie ihn. Ab der nächsten Story wird kanman:

1. aus dem Demonstrate-Block eine Spec schreiben, wenn die Story Richtung Ready geht
2. prüfen, dass die Spec fehlschlägt und ihr eigenes Ziel nicht mockt, und sie dann auf den Branch kanman/spec/<KEY> committen
3. sie nach der Umsetzung gegen eine frische Umgebung ausführen, danach noch einmal auf einem frischen Checkout
4. die Artefakte speichern und im Nachweispaket verlinken

Eine Einstellung für viele Repositories

Ein Team mit vielen ähnlichen Repositories, zum Beispiel Dutzenden Go-Services, braucht nicht in jedem ein Manifest. Legen Sie unter Team-Einstellungen > Prüfungen und Auslieferung, im ausklappbaren Bereich mit den Standard-Prüfdateien, einen Standard für Abnahmeprüfungen für das Team fest:

• Abnahmeprüfungen nehmen den Inhalt einer .kanman/acceptance.json auf, Lokale Prüfungen vor dem Review den Inhalt einer .kanman/verify.json. kanman prüft beide schon beim Tippen und speichert sie nur, wenn sie gültig sind.
• Jedes Repository des Teams ohne eigene Datei nutzt den Standard. Eine Datei im Repository hat immer Vorrang, ein besonderes Repository kann also seine eigene Einstellung behalten.
• {KEY} steht im Spec-Ordner, in spec_arg und im Run-Befehl für den Story-Schlüssel, zum Beispiel go test ./.kanman/acceptance/{KEY}/....
• Secrets unter run.secrets folgen denselben Regeln wie in einem Repository: Sie erreichen setup und run nur, wenn das Team sie nutzen darf (die Secrets unter Was ich ändern darf in Team-Einstellungen > Grenzen und Budgets), und ihre Werte erscheinen nie in Logs.
• Team-Einstellungen > Repositories und Tracker zeigt jedes Repository ohne eigene Datei als Nutzt den Standard des Teams für Abnahmeprüfungen.

Ein Beispiel für Go-Services, deren private Module aus Ihrem GitLab kommen, mit einem Lese-Token, das dem Team als Secret FM_GITLAB_READ_TOKEN freigegeben ist. Die Go-Toolchain und die Git-Anmeldedaten für die privaten Module kommen aus der Team-Umgebung (Image golang:1.25, ihr Einrichtungsschritt); die Befehle bleiben also einfach, und der Runner braucht nur Docker:

{
  "version": 1,
  "provision": { "type": "apply", "command": "true" },
  "setup": "go mod download",
  "run": {
    "command": "go test ./.kanman/acceptance/{KEY}/...",
    "secrets": ["FM_GITLAB_READ_TOKEN"]
  },
  "framework": "other",
  "artifacts": []
}

Private Module werden in setup geladen, nicht in provision: Nur setup und run erhalten Secrets.

Andere Frameworks als Playwright

Das Manifest ist frameworkunabhängig. Setzen Sie framework auf playwright, vitest, jest, pytest oder other und richten Sie run.command auf Ihren Test-Runner:

{
  "version": 1,
  "provision": { "type": "docker_compose", "file": "docker-compose.acceptance.yml" },
  "ready_url": "http://localhost:8000/health",
  "run": { "command": "pytest", "spec_arg": ".kanman/acceptance/{KEY}/" },
  "framework": "pytest",
  "artifacts": ["reports/**"]
}

Häufige Probleme