Fuzzball Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

Catalog Repositories

A catalog repository is an external Git repository of application templates that Fuzzball imports into the workflow catalog. You maintain the templates in a version control system such as GitHub or GitLab, and Fuzzball synchronizes them into your deployment.

Two terms appear throughout this section. A catalog repository is the Git repository that holds the templates. A catalog source is Fuzzball’s registration of that repository – what the fuzzball workflow catalog source commands create, list, and remove. Removing a source leaves the Git repository at its origin untouched.

In This Section

  • Repository Structure - The directory layout, required files, and frontmatter a catalog repository must provide
  • User Commands - For regular users and group owners to manage their own catalog repositories
  • Admin Commands - For administrators to manage catalog repositories system-wide

Permissions and Ownership

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. This owner kind is reserved for the built-in CIQ catalog and cannot be assigned when adding a repository

A user’s role also governs whether they can import and manage catalog repositories.

Using Applications from 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 do not appear in Fuzzball until you run reload for that repository, or until the next periodic catalog sync. The sync runs every four hours by default; administrators can change that schedule – see Configuring the Sync Schedule.

Application IDs

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.

Example: CIQ Official Catalog

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

Use this repository as a reference when structuring your own.