Packs erstellen

Überblick

Packs sind die Distributionseinheit in Greentic. Diese Anleitung behandelt das Erstellen, Bauen, Signieren und Veröffentlichen von Packs mit den CLI-Tools.

Pack-CLI-Befehle

gtc pack

gtc pack <COMMAND>

Commands:
  build     Build a pack from source directory
  verify    Verify pack signature and contents
  info      Display pack metadata
  extract   Extract pack contents
  sign      Sign a pack
  publish   Publish pack to registry

Ein Pack erstellen

1. Pack-Verzeichnisstruktur erstellen

   mkdir -p my-pack/{flows,components,assets}

2. Pack-Manifest erstellen

   my-pack/pack.toml

   [pack]
   name = "my-feature"
   version = "1.0.0"
   description = "My awesome feature pack"
   authors = ["Your Name <you@example.com>"]
   
   [capabilities]
   id = "greentic.cap.app.v1"
   provides = ["my-feature"]
   
   [flows]
   main = "flows/main.ygtc"
   
   [components]
   processor = "components/processor.wasm"
   
   [assets]
   templates = "assets/templates/"

3. Flows hinzufügen

   my-pack/flows/main.ygtc

   name: main
   version: "1.0"
   description: Main flow
   
   nodes:
     - id: process
       type: reply
       config:
         message: "Hello from my pack!"
   
   triggers:
     - type: message
       target: process

4. Komponenten hinzufügen (falls vorhanden)

   WASM-Komponenten bauen und in components/ ablegen:

   cd my-component
   cargo build --target wasm32-wasip2 --release
   cp target/wasm32-wasip2/release/my_component.wasm ../my-pack/components/

Packs bauen

Einfacher Build

gtc pack build ./my-pack

# Output: my-feature-1.0.0.gtpack

Build mit Optionen

# Specify output path
gtc pack build ./my-pack --output ./dist/my-feature.gtpack

# Skip WASM optimization
gtc pack build ./my-pack --no-optimize

# Include debug info
gtc pack build ./my-pack --debug

Build-Ausgabe

• Ordnermy-feature-1.0.0.gtpack

  • manifest.cbor
  • Ordnerflows/

    • main.ygtc
  • Ordnercomponents/

    • processor.wasm
  • Ordnerassets/

    • Ordnertemplates/

      • …
  • sbom.json

Packs signieren

Achtung

Signiere Packs immer vor der Verteilung. Unsigned Packs können in Produktionsumgebungen von der Runtime abgelehnt werden.

Signaturschlüssel erzeugen

# Generate new Ed25519 key pair
gtc pack keygen --output my-signing-key

# Creates:
# - my-signing-key.pem (private key - keep secret!)
# - my-signing-key.pub (public key - distribute)

Ein Pack signieren

gtc pack sign my-feature-1.0.0.gtpack --key my-signing-key.pem

# Output: my-feature-1.0.0.gtpack (updated with signature)

Signatur verifizieren

gtc pack verify my-feature-1.0.0.gtpack --pubkey my-signing-key.pub

# Output: Signature valid

Pack-Inspektion

Metadaten anzeigen

gtc pack info my-feature-1.0.0.gtpack

Ausgabe:

Pack: my-feature
Version: 1.0.0
Description: My awesome feature pack
Authors: Your Name <you@example.com>

Capabilities:
  ID: greentic.cap.app.v1
  Provides: my-feature

Contents:
  Flows: 1
  Components: 1
  Assets: 2 directories

Signature: Valid (signed by: ABC123...)

Inhalt auflisten

gtc pack info my-feature-1.0.0.gtpack --list

# Lists all files in the pack

Pack extrahieren

gtc pack extract my-feature-1.0.0.gtpack --output ./extracted/

# Extracts pack contents for inspection

Flow-Validierung

Flows validieren

# Validate all flows in a directory
gtc flow doctor ./my-pack/flows/

# Validate specific flow
gtc flow validate ./my-pack/flows/main.ygtc

Doctor-Ausgabe

gtc flow doctor ./flows/
# Output:
# Checking flows/main.ygtc... OK
# Checking flows/helper.ygtc... OK
#
# 2 flows checked, 0 errors, 0 warnings

Häufige Validierungsfehler

Fehler	Ursache	Lösung
Unknown node type	Ungültiger Knotentyp	Verfügbare Knotentypen prüfen
Missing target node	Edge verweist auf einen nicht existierenden Knoten	Referenz auf die Knoten-ID korrigieren
Circular dependency	Knoten bilden einen Zyklus	Den Zyklus aufbrechen
No trigger defined	Flow hat keinen Einstiegspunkt	Einen Trigger hinzufügen

Packs veröffentlichen

In OCI-Registry veröffentlichen

# Login to registry
gtc pack login ghcr.io --username USER --password TOKEN

# Publish pack
gtc pack publish my-feature-1.0.0.gtpack --registry ghcr.io/greentic

Aus der Registry ziehen

gtc pack pull ghcr.io/greentic/my-feature:1.0.0

In einem Bundle verwenden

greentic.demo.yaml

apps:
  my-app:
    pack: "oci://ghcr.io/greentic/my-feature:1.0.0"

Pack-Vorlagen

Vorlage für ein Provider-Pack

pack.toml

[pack]
name = "messaging-custom"
version = "1.0.0"
description = "Custom messaging provider"

[capabilities]
id = "greentic.cap.messaging.provider.v1"
provides = ["custom"]

[flows]
setup_default = "flows/setup.ygtc"
verify_webhooks = "flows/verify.ygtc"

[components]
ingress = "components/ingress.wasm"
egress = "components/egress.wasm"
operator = "components/operator.wasm"

[secrets]
required = ["api_key"]
optional = ["webhook_secret"]

Vorlage für ein Application-Pack

pack.toml

[pack]
name = "helpdesk-bot"
version = "1.0.0"
description = "IT Helpdesk bot"

[capabilities]
id = "greentic.cap.app.v1"
provides = ["helpdesk"]

[dependencies]
greentic-templates = "^0.4"
greentic-llm-openai = "^0.4"

[flows]
on_message = "flows/on_message.ygtc"
on_ticket = "flows/on_ticket.ygtc"

[assets]
cards = "assets/cards/"
templates = "assets/templates/"

Best Practices

1. Semantisch versionieren - Verwende semver (MAJOR.MINOR.PATCH)
2. Alle Releases signieren - Verteile niemals unsignierte Packs
3. SBOM einbinden - Dokumentiere Abhängigkeiten für Sicherheitsprüfungen
4. Vor dem Veröffentlichen testen - Flows validieren und Komponenten testen
5. Gründlich dokumentieren - Eine README in das Pack aufnehmen
6. Packs fokussiert halten - Ein Feature oder Provider pro Pack
7. CI/CD verwenden - Build und Veröffentlichung automatisieren

CI/CD-Beispiel

.github/workflows/pack.yml

name: Build and Publish Pack

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@1.90.0

      - name: Build Pack
        run: gtc pack build ./my-pack

      - name: Sign Pack
        run: |
          echo "${{ secrets.SIGNING_KEY }}" > key.pem
          gtc pack sign my-feature-*.gtpack --key key.pem

      - name: Publish
        run: |
          gtc pack login ghcr.io --username ${{ github.actor }} --password ${{ secrets.GITHUB_TOKEN }}
          gtc pack publish my-feature-*.gtpack --registry ghcr.io/${{ github.repository }}

Nächste Schritte

• Pack-Format-Referenz - Vollständige Spezifikation
• Flow-Schema-Referenz - YAML-Schema
• Komponentenleitfaden - WASM-Komponenten bauen