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)
    ├── hello-world-spanish/
    │   ├── metadata.md          (reuses hello-world's template)
    │   └── values.yaml
    └── ...

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

Each application directory must contain metadata.md, values.yaml, and a template. The template is normally the directory’s own template.yaml, but an entry can instead reuse a template from another entry.

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

• id: An identifier for the application, unique within this repository. Any valid string is allowed. Fuzzball combines it with the catalog source that imported the repository to derive the application’s ID, so two catalog sources can use the same id without affecting one another – each gets its own application. Two entries in the same repository that share an id are a conflict: Fuzzball keeps the first by directory name and skips the rest with a warning in the orchestrate log.
• 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 catalog 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
• template: Directory name (not id or name) of another application in the same repository whose template this application uses. Only valid when the application has no template.yaml of its own – see Reusing a template from another entry.

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: v4
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.

An application that differs from an existing one only in its default values can point at that application’s template instead of copying it. Add a template field to the frontmatter and leave out template.yaml:

---
id: https://example.com/apps/hello-world-spanish
name: Hello World (Spanish)
category: EXAMPLES
template: hello-world
---
The Hello World workflow, preconfigured with Spanish defaults.

The value of template is the other application’s directory name under applications/ – hello-world above. It is not that application’s id and not its name, both of which are usually different from its directory name.

The application still needs its own metadata.md and values.yaml; only the template is shared. When the referenced template changes, every application referencing it picks up the change on the next sync.

References resolve within a single repository and one level deep, so the referenced application must have a template.yaml of its own. An application is skipped with a warning in the orchestrate logs, and does not appear in the catalog, when it references an application that does not exist or that has no template of its own, when it has both a template.yaml and a template reference, or when it has neither.

Template references require a Fuzzball release that supports them. An older deployment does not simply skip a referencing application – it fails the repository sync altogether, so no application in that repository is updated. Do not add referencing applications to a repository until every deployment reading it has been upgraded.

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, bool_value, secret_value, or volume_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.

Each application’s ID is derived from its catalog source and its id frontmatter field, so an application keeps the same ID across syncs. Refer to an application by name where you can; a UUID is only stable for as long as the application stays in the same catalog source. Removing a catalog source and adding it again normally gives it a new source ID, and therefore gives its applications new IDs.

Applications imported before Fuzzball scoped IDs to their catalog source were assigned new IDs by the first sync after the upgrade, so saved links and scripts that refer to a catalog application by UUID need updating. Look the current ID up with fuzzball workflow catalog list.

An application that belonged to a single catalog source keeps its usage history. Where two sources had both imported the same id, they had been sharing one application: it stays with the source that first created it, and the other source gets a new application of its own, starting with no usage history.

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.