Author Catalog Resources
artifacthub-shim indexes Tekton resources from the configured filesystem and
Git catalog sources. A catalog can contain Task, Pipeline, and StepAction
resources. Each resource is versioned by directory and exposed through the
DevOps Hub UI, Artifact Hub-compatible APIs, and the Tekton hub resolver.
If the catalog is stored in Git, configure the source before testing the
resource. See Configure Custom Git Repositories
for the required repository.yaml structure, catalog paths, repository names,
visibility, credentials, and extraResources settings.
TOC
Catalog Directory LayoutResource MetadataComplete Task ExampleComplete Pipeline ExampleSupporting ConfigMapsInitialize and Version a CatalogChange a Published VersionUse Resources with the Hub ResolverRecommended SettingsValidation ChecklistCatalog Directory Layout
Use the following layout for a catalog repository. The root README.md and
OWNERS files are recommended for maintainers; the shim indexes resources
under the task/, pipeline/, and stepaction/ directories.
Follow these rules:
- Use the lowercase resource kind as the top-level directory:
task,pipeline, orstepaction. - Use
<kind>/<name>/<version>/for every package version. Version directory names should be semantic-version-compatible, such as0.1,0.2, or1.0.0. - Store the manifest as
<name>.yamlor<name>.yml. The shim prefers this filename. If it is absent, it can discover the only YAML file in the version directory whose Kuberneteskindmatches the configured source kind. - The manifest
metadata.namemust equal the package directory name, and the manifestkindmust match the top-level source directory. - Do not publish both versions that normalize to the same semantic version,
such as
0.1and0.1.0, for the same package. They create an ambiguous resolver lookup. - Put a version-specific
README.mdbeside the manifest. It is optional for indexing, but is displayed on resource detail pages and should document parameters, workspaces, results, examples, and compatibility. samples/andOWNERSare optional. They are not indexed as manifests, but are useful for review and user documentation.- Keep ordinary repository files outside the resource version directories.
artifacthub-shimdoes not require anartifacthub-repo.ymlfile.
The config/ directory is for supporting ConfigMaps, such as tool image
options and overview templates. These files are not catalog packages. They are
imported only when the configured source uses extraResources and the
ConfigMap has the import label described in Configure Custom Git
Repositories.
Resource Metadata
The shim requires a valid YAML manifest with kind and metadata.name, and it
rejects a resource when those values do not match the configured source and
package directory. The following metadata is the catalog publication contract:
artifacthub-shim preserves all manifest labels and annotations in its API
responses. The current parser only rejects malformed YAML, a missing kind, a
missing name, or a kind/name mismatch; it does not reject an otherwise valid
manifest solely because an optional annotation is absent. Nevertheless, keep
the publication metadata above on every released version so that the resource
has complete UI, search, compatibility, and Artifact Hub metadata.
Keep any existing style.tekton.dev/descriptors annotations unchanged. They
drive dynamic forms and are not rewritten or generated by the shim. For
ConfigMaps that must be synchronized into the cluster, use the separate
artifacthub-shim.alauda.io/import: "true" label; do not put that label on a
Task, Pipeline, or StepAction manifest.
Complete Task Example
The following manifest belongs at
task/echo-hello/0.1/echo-hello.yaml:
Complete Pipeline Example
The following manifest belongs at
pipeline/hello-pipeline/0.1/hello-pipeline.yaml:
Use Task, Pipeline, and StepAction resources with the current Tekton API
version supported by the target platform. Do not add new ClusterTask
resources; namespaced Task resources are used with Tekton Pipelines v1.
Supporting ConfigMaps
Use config/ with a Git extraResources entry when a catalog release must
install supporting ConfigMaps. Only apiVersion: v1, kind: ConfigMap
documents with the import label are synchronized. The target namespace must be
allowed by config.extraResourceSync.allowedNamespaces (the default is
kube-public).
Unlabeled ConfigMaps, non-ConfigMap resources, and unrelated files are skipped.
If a synchronized ConfigMap must remain after it is removed from Git, add
artifacthub-shim.alauda.io/resource-policy: keep to the in-cluster resource.
See Add Custom Task Images to Selector
and Customize Task Overview with Templates
for the labels required by those UI features.
Initialize and Version a Catalog
Create the initial repository structure with:
Keep multiple versions in separate directories. Use a new version when the
resource contract or behavior changes, and document breaking changes in the
version README.md. Before publishing a new version, verify that its directory
name, version label, manifest name, and README all describe the same release.
The root OWNERS file is repository metadata for maintainers, for example:
Change a Published Version
A published version directory is not frozen. When the manifest or the
README.md of an existing <kind>/<name>/<version>/ directory changes in the
source, the shim serves the new content after its next refresh. These are the
only two files the shim serves for a version; other files in the directory,
such as samples/ and OWNERS, are not served as version content. Refreshes run every
config.refreshInterval (default 10m, set through the
ARTIFACTHUB_SHIM_REFRESH_INTERVAL environment variable; see
Chart Configuration). A repository
ConfigMap or Secret event starts one after the event debounce window
(config.repositoryEventDebounce, default 2s); a Kubernetes catalog source
event requests one directly, without that window. Each refresh fetches Git sources again, rebuilds the whole index,
and atomically replaces the served snapshot. The shim does not compare a
version with the previous snapshot, so it neither rejects nor reports an
in-place change. The digest reported for a version is the SHA-256 of its
manifest: it changes when the manifest changes, and stays the same for a
README-only change. Resolver requests for that name and version receive
the new content after the refresh. Each replica refreshes on its own. When a
source fails to load with a transient error, the replica keeps serving that
source's last successfully loaded content only if it has loaded the source
successfully before and the source configuration has not changed since;
otherwise the source is reported as invalid.
Treat a published version as final. To fix or change a released resource,
publish a new version directory and update the references to it. To freeze
the files of a Git source, set its revision to a commit instead of a branch.
This freezes only that source's files: which versions the shim serves still
depends on the catalog configuration, such as repositories added or removed
through repository ConfigMaps or Kubernetes catalog sources, and
config.disabledPackages rules (see Chart
Configuration). A Git source
pinned to a commit serves only what that commit contains, so after you
publish a new version directory, also move the source's revision to a
commit that contains it; otherwise the new version is not served.
Use Resources with the Hub Resolver
For artifacthub-shim, set the resolver type to artifact. The catalog
value is the built-in or configured repository name, not the Git repository URL
or local directory name.
Built-in repository names are:
The StepAction repository is registered only when the packaged catalog contains
a stepaction/ directory. A custom Git repository uses the nested
repositories[].name value from repository.yaml as its catalog parameter.
For example, if the repository is named team-a-tasks, use:
The main resolver parameters are:
For the complete resolver configuration and troubleshooting guidance, see Consume Resources with the Hub Resolver.
Recommended Settings
When to enable. Use a shared catalog when several projects need the same build, scan, or delivery steps.
Recommended values. Register the catalog as one Git repository entry, with
one stable repository name per kind, as described in Configure Custom Git
Repositories: add one
nested repositories entry with kind: task and another with kind: pipeline,
because each nested entry declares exactly one kind and its name becomes the
catalog parameter that resolver references use. Keep the
task/<name>/<version>/<name>.yaml and pipeline/<name>/<version>/<name>.yaml
paths from Catalog Directory Layout. Publish a new version directory whenever a
resource contract or behavior changes, following Initialize and Version a
Catalog. Keep every resource self-contained for air-gapped runs: resolve Tasks
and Pipelines from this catalog through the hub resolver, and reference step
images from the private registry that serves the environment (see Built-in
Tool Images Selection Guide), or pin them by
digest. Require review before publishing: list approvers and reviewers in
the root OWNERS file and pass the Validation Checklist below for every
version. In resolver references, set type: artifact, the catalog name
configured for the resource's kind, and an explicit version, because the hub
resolver rejects a reference without version
(missing required hub resolver params: version).
Prerequisites. artifacthub-shim is installed with
config.enableConfigMapSources set to true so that Git sources can be
registered. The Tekton hub resolver is enabled and points to the shim, as
described in Consume Resources with the Hub
Resolver. The Git server
that hosts the catalog is reachable from the cluster, and every step image the
catalog references is available in the environment's registry.
Validation Checklist
Before publishing a catalog, check every resource version:
- The path follows
<kind>/<name>/<version>/<name>.yaml. - The manifest kind and
metadata.namematch the source kind and package directory. -
app.kubernetes.io/versionmatches the version directory. -
spec.descriptionis present and useful. -
tekton.dev/pipelines.minVersionstates the minimum compatible upstream Tekton version. -
tekton.dev/displayName,tekton.dev/categories,tekton.dev/tags, andtekton.dev/platformsare provided when applicable. -
artifacthub.io/licenseandartifacthub.io/categoryare present; deprecated versions haveartifacthub.io/deprecated: "true". - Parameters, workspaces, results, and examples have descriptions where applicable.
- Each version has a README with runnable examples.
- Samples and resolver references use
type: artifact. - ConfigMaps intended for synchronization have
artifacthub-shim.alauda.io/import: "true"and an allowed namespace. - No package contains normalized version duplicates such as
0.1and0.1.0.
Useful local checks include:
After the repository is pushed, configure its Git source and verify that the
repository ConfigMap reports RepositoryConfigAccepted and its source reports
RepositorySourceReady events. The Git source, repository name, credentials,
visibility, and extraResources rules are documented in Configure Custom Git
Repositories.