Building Packs

Overview

Packs are the distribution unit in Greentic. This guide covers creating, building, signing, and publishing packs using the CLI tools.

Pack CLI Commands

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

Creating a Pack

Create pack directory structure
Terminal window
```
mkdir -p my-pack/{flows,components,assets}
```

Create pack manifest

[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/"

Add flows

name: main
version: "1.0"
description: Main flow

nodes:
  - id: process
    type: reply
    config:
      message: "Hello from my pack!"

triggers:
  - type: message
    target: process

Add components (if any)

Build WASM components and place in components/:

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

Building Packs

Basic Build

gtc pack build ./my-pack

# Output: my-feature-1.0.0.gtpack

Build with Options

# 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 Output

Directorymy-feature-1.0.0.gtpack
- manifest.cbor
- Directoryflows/
  - main.ygtc
- Directorycomponents/
  - processor.wasm
- Directoryassets/
  - Directorytemplates/
    …
- sbom.json

Signing Packs

Generate Signing Key

# 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)

Sign a Pack

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

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

Verify Signature

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

# Output: Signature valid

Pack Inspection

View Metadata

gtc pack info my-feature-1.0.0.gtpack

Output:

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...)

List Contents

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

# Lists all files in the pack

Extract Pack

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

# Extracts pack contents for inspection

Flow Validation

Validate Flows

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

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

Doctor Output

gtc flow doctor ./flows/

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

Common Validation Errors

Error	Cause	Fix
`Unknown node type`	Invalid node type	Check available node types
`Missing target node`	Edge points to non-existent node	Fix node ID reference
`Circular dependency`	Nodes form a cycle	Break the cycle
`No trigger defined`	Flow has no entry point	Add a trigger

Publishing Packs

Publish to OCI Registry

# 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

Pull from Registry

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

Use in Bundle

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

Pack Templates

Provider Pack Template

[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"]

Application Pack Template

[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

Version semantically - Use semver (MAJOR.MINOR.PATCH)
Sign all releases - Never distribute unsigned packs
Include SBOM - Document dependencies for security audits
Test before publishing - Validate flows and test components
Document thoroughly - Include README in pack
Keep packs focused - One feature or provider per pack
Use CI/CD - Automate build and publish

CI/CD Example

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

Next Steps

Pack Format Reference - Complete specification
Flow Schema Reference - YAML schema
Components Guide - Building WASM components