Publish image build artifacts to the Red Hat Edge Manager Software Catalog by creating an ImagePromotion resource. The promotion copies registry references and export artifacts into a CatalogItem version so operators can deploy from the catalog without entering OCI image references manually.

Build, promote, and deploy

The integrated workflow connects Image Builder and the Software Catalog:

1. An administrator configures trusted base images on OCI repositories. See Configuring trusted base images on an OCI repository in the Additional resources section.
2. You create an ImageBuild and optional ImageExport tasks by using the simplified workflow or the CLI. See Building images with the simplified workflow in the Additional resources section.
3. You publish the build to the catalog. Enable Publish to Software Catalog when you create the build in the web console, or create an ImagePromotion after the build completes.
4. The service waits for required artifacts, publishes catalog metadata, and moves the promotion through lifecycle states until it reaches Completed or Failed.
5. Operators browse catalog items in the Software Catalog and deploy or update devices and fleets. See Using the Software Catalog in the Additional resources section.

You can also synchronize catalog definitions from Git by using a catalog ResourceSync. Git-synchronized catalogs and image-promoted catalog items can coexist. For Git-based catalog administration, see Managing a catalog repository on the CLI in the Additional resources section.

Default catalog

Every organization receives a default catalog automatically when the organization is first provisioned. You can publish image builds to this catalog without creating a Catalog resource first. Verify that the catalog exists by running flightctl get catalog/default.

Promotion lifecycle states

An ImagePromotion moves through the following phases in status.phase:

When you append export formats to an existing promotion (amendment), the service sets status.lastAmendedAt and might move the promotion back through Publishing toward Completed.

Catalog targets

In spec.target, choose one of the following target types:

• New catalog item: Creates a new CatalogItem in the selected catalog with the version and artifact references from the promotion.
• Existing catalog item: Adds a new version entry to an existing CatalogItem, preserving version history on the same item (for example 1.0.0 1.1.0).

New promotions assign the published catalog item version to the testing channel automatically. You cannot choose a different channel in an ImagePromotion manifest. Plan channel promotion separately if your organization uses multiple channels in catalog definitions.

Role-based access

Catalog publication is gated through ImagePromotion:

• Users with the Operator, OrgAdmin, or Admin role can create, read, update, and delete ImagePromotion resources and can create new image build versions.
• Direct create, update, patch, and delete operations on catalogs and catalogitems are reserved for Admin and OrgAdmin roles (not Operator).

If Operator accounts require direct catalog write access, see Restoring catalog write access for Operator accounts in the Additional resources section.

Rebuild and version lineage

To produce a new image version from an existing build, use the flightctl new-version command or the New version action in the web console. The service copies the parent build specification and records lineage in the flightctl.io/new-version-from annotation. An optional publish step prefills the catalog name, catalog item name, incremented version, and replaces from the parent’s last successful promotion. See Creating a new image version and Publishing an image build to the Software Catalog in the Additional resources section.