Publish a new version after a rebuild

When a patch or configuration change requires a new image version on the same catalog item, create a new build version and publish it.

Procedure

  1. Create a new build version from the parent build: 
    $ flightctl new-version imagebuild/<parent_build_name> --name <new_build_name>

    Alternatively, use the New version action in the web console. The optional publish step can prefill the following fields from the parent’s last successful promotion:

    • Target catalog name
    • Catalog item name
    • Version (patch increment of the last published version, for example 1.0.0 1.0.1)
    • replaces value (the previous published version)
  2. Wait for the new build (and any exports) to complete.
  3. If you did not publish automatically from the New version workflow, create an ImagePromotion that references the new build. Target the existing catalog item with an incremented version and a replaces value. For an example, see the Additional resources section.

Results

  • flightctl get imagepromotion/<promotion_name> reports status.phase: Completed.
  • The Software Catalog shows the new version on the catalog item.
  • Operators with catalog access can deploy the version to a device or fleet.
  • Promotion stays in WaitingForArtifacts: One or more formats in exportFormats is not yet available. The promotion waits for a new successful export rather than failing immediately when an export attempt fails. Check ImageExport status, wait for a successful export, or remove formats you do not need from exportFormats.
  • Promotion phase is Failed: Inspect status.conditions and events on the promotion and the referenced ImageBuild. If the referenced build failed or was canceled, create a new build and a new ImagePromotion.
  • 400 when creating a promotion — version already exists: The target catalog item already contains the version you specified. Choose a new semver version or target a different catalog item.
  • 409 Conflict when creating a new catalog item: A catalog item with that name already exists. Choose Existing catalog item instead, or pick a different name.
  • 404 Not Found when adding to an existing catalog item: No catalog item with that name exists. Choose New catalog item instead, or check the catalog item name spelling.
  • 403 when writing catalog resources directly: Catalog writes for Operators are gated through ImagePromotion. See Restoring catalog write access for Operator accounts in the Additional resources section.

For field-level details, see ImagePromotion resource reference in the Additional resources section.