Catalog Repositories

Catalog repositories allow you to import a set of application templates from external Git repositories into the Fuzzball workflow catalog. This enables you to maintain workflow templates in version control systems like GitHub or GitLab, and automatically synchronize them with your Fuzzball deployment.

A catalog repository is a Git repository with a specific directory structure. The repository must contain an applications/ directory at its root, with each application in its own subdirectory:

your-catalog-repository/
└── applications/
    ├── hello-world/
    │   ├── metadata.md
    │   ├── template.yaml
    │   ├── values.yaml
    │   └── icon.png (optional)
    ├── data-processing/
    │   ├── metadata.md
    │   ├── template.yaml
    │   ├── values.yaml
    │   └── banner.jpg (optional)
    └── ...

See the CIQ workflow template repository for an example of repository structure.

Each application directory must contain three files:

A Markdown file with YAML frontmatter containing application metadata. The frontmatter must include:

• id: A unique identifier for the application. Any unique valid string is allowed. One way of managing IDs would be to incorporate the base URL of the repository (e.g. https://github.com/<ORG>/<REPO>/applications/<APP>) or some other hierarchical scheme.
• name: The display name for the application
• category: The category to organize the application under. A list of available categories can be obtained with fuzzball workflow-template list-categories.
• description: A description of the application (in the Markdown body, not the frontmatter)

Optional frontmatter fields:

• featured: Set to true to mark this application as featured (default: false)
• key_art: Filename of an image file in the same directory to use as key art
• tags: List of tags for categorizing and searching

Example metadata.md:

---
id: https://example.com/apps/hello-world
name: Hello World
category: EXAMPLES
featured: false
key_art: icon.png
tags:
  - tutorial
  - beginner
---
This is a simple Hello World workflow that demonstrates basic Fuzzball functionality.

It prints a greeting message and can be customized with different container images.

When writing the description, put the most important information at the beginning. The workflow catalog displays only the first 2-4 lines in card view, though the full description is visible on the detail page.

A Fuzzfile template with placeholders for user-customizable values.

Example template.yaml:

{{- $shout := (default "Hello, world!" .Message | trim | upper) }}
version: v1
jobs:
  hello:
    image:
      uri: {{ .ContainerUri }}
    script: |
      #!/bin/sh
      echo "SHOUT: {{ $shout }}"
    resource:
      cpu:
        cores: {{ .Cores }}
      memory:
        size: {{ .Memory }}

The templating feature uses Go text/template and slim-sprig, allowing complex operations like conditional logic.

Defines all variables used in the template with their default values and descriptions.

Example values.yaml:

values:
  - name: ContainerUri
    display_name: Container image URI
    string_value: docker://alpine:latest
  - name: Message
    display_name: Message to display
    string_value: "Hello, world!"
  - name: Cores
    display_name: Number of CPU cores
    uint_value: 1
  - name: Memory
    display_name: Memory allocation
    string_value: 1GiB

Each value entry requires:

• name: Variable name (matching the template placeholder without the dot)
• display_name: User-friendly description
• Value type: One of string_value, uint_value, float_value, or bool_value

You can include image files (.png, .jpg, .jpeg, .webp, .svg) in each application directory for use as key art or icons. Reference these files using the key_art field in the metadata. You can also include subdirectories for scripts and other supplementary files that could be pulled into the workflow by data ingress.

Fuzzball provides different command sets for managing catalog repositories depending on your role:

• User Commands - For regular users and group owners to manage their own catalog repositories
• Admin Commands - For administrators to manage catalog repositories system-wide

Applications imported from a catalog repository inherit the repository’s owner kind, which determines who can view and use the applications:

• group: Applications are visible within your group
• organization: Applications are shared across your organization
• provider: Applications are available system-wide (reserved for administrators)

In addition a user’s role also governs their ability to import and manage catalog repositories.

Once a catalog repository is synchronized, its applications appear in the workflow catalog alongside manually created templates and the applications from the CIQ catalog (if enabled). You can use them exactly as described in the Fuzzfiles From Existing Templates section.

Changes to templates in the catalog repository won’t appear in Fuzzball until you manually run the reload command for that repository or until the periodic catalog sync runs automatically.

CIQ maintains an official catalog repository with example workflows and common applications at:

• Repository: https://github.com/ctrliq/ciq-fuzzball-catalog
• Branch: Typically versioned branches like v3.0

You can use this as a reference for structuring your own catalog repositories.