Recommendation Catalog

The recommendation catalog is the shared index that the Recommendations page browses. It lists recommendations published by Trailer and by the community, so an administrator can install one without writing it. The default catalog is https://catalog.trailer.dev.

This page explains how the catalog discovers recommendations and how you publish your own into it. For how a recommendation is installed, configured, and run once it is listed, see Recommendations.

How the catalog finds recommendations

The catalog is built from public GitHub repositories. On a regular schedule it searches GitHub for repositories that carry the topic trailer-recommendation, reads a manifest from each match, and indexes it. There is no separate submission form or approval step. A repository that carries the topic and a valid manifest is picked up on its own.

Only public repositories with that topic are considered. To get your recommendation listed, you publish it as one of these repositories. To take it down, remove the topic or the repository.

What a recommendation repository needs

Three things:

1. The topic trailer-recommendation on the GitHub repository. This is how the catalog finds it.
2. A manifest named trailer.yml at the root of the repository. The catalog reads it to learn what the recommendation is.
3. At least one Git tag. Versions come from tags. A repository with no tags is skipped.

The manifest

trailer.yml describes the recommendation:

Field	Required	Meaning
name	yes	The name shown on the catalog card.
type	yes	image or workspace, the kind of draft the recommendation applies to.
runtime	yes	starlark, go, or wasm, the runtime that holds the logic.
import	yes	The entry point inside the repository. For Starlark and WebAssembly it is the path to the source file the runtime loads. For Go it is the module path, mounted under src/.
description	no	A short summary shown on the card.
iconUrl	no	URL of an icon shown on the card.
defaultConfiguration	no	Configuration preloaded when the recommendation is installed. Defaults to an empty object.

Example trailer.yml:

name: PyTorch shared memory
type: workspace
runtime: starlark
import: main.star
description: Raises the shared memory size when PyTorch is detected in the image.
iconUrl: https://example.com/icon.png

The manifest is read from the commit that the newest tag points at, so it must be present and valid at that tagged commit.

The Starlark example recommendation is a complete, working repository you can copy as a starting point.

Publishing your own recommendation

1. Create a public GitHub repository.
2. Write the recommendation logic in one of the supported runtimes (Starlark, Go, or WebAssembly). The Recommendations page describes what the match and recommend logic works with.
3. Add a trailer.yml manifest at the root, with import pointing at your entry point.
4. Add the topic trailer-recommendation to the repository, from the About panel on the repository’s GitHub page.
5. Create a Git tag for your first version and push it, for example v1.0.0.

Within a short indexing interval the recommendation appears in the default catalog, and administrators can install it from their Recommendations page.

Versions and updates

Every version is a Git tag. The newest tag is offered as the latest version, and all tags are available to install. To release an update, push a new tag. The catalog picks it up on its next pass and adds it to the version list.

When an administrator installs a version, their instance pins it to that tag’s commit. If you later move or delete a tag so that its commit changes, existing installs of that version stop loading, as described in Recommendations.

Author, official badge and stars

• Author is the owner of the GitHub repository.
• Stars mirror the repository’s GitHub star count, so sorting the catalog by stars reflects GitHub popularity.
• The official badge is not something you set. It is applied automatically, and only to repositories owned by the Trailer organization. Community recommendations are listed the same way, just without the badge.

When a recommendation drops out

The catalog rechecks listed recommendations on a schedule. If a repository can no longer be reached, or its latest version tag no longer resolves because the repository was deleted, made private, or the tag was removed, the recommendation is dropped from the catalog automatically.

Using a different catalog

The default catalog at https://catalog.trailer.dev indexes the public community and official recommendations. An instance can point at additional catalog servers, configured on the Settings page. You can also install a recommendation straight from the host filesystem without any catalog, covered under local recommendations on the Recommendations page.

Related Pages

• Recommendations - Browse, install, and configure recommendations
• Settings - Configure catalog servers
• Create Image - Where image recommendations surface
• Create Workspace - Where workspace recommendations surface