Edit

Migrate to the versions.env Workflow

Purpose: For platform engineers maintaining an older project, migrates from manually editing config/components.yaml to the current workflow where config/versions.env is the source of truth and components.yaml is auto-generated.

What changed

| Old workflow | Current workflow | |---|---| | opencenter-airgap init --create-manifest | opencenter-airgap init | | Hand-edit config/components.yaml | Edit config/versions.env | | opencenter-airgap build | opencenter-airgap build (auto-generates components.yaml) | | (no equivalent) | opencenter-airgap build --force-regenerate to discard manual edits | | (no equivalent) | opencenter-airgap scan --repos to clone repos and discover images |

The --create-manifest flag is gone. The build now generates config/components.yaml from config/versions.env on first run and merges any manual edits on subsequent runs.

Backward compatibility

Existing projects keep working:

  • If config/components.yaml is newer than config/versions.env, the build uses it as-is.

  • If config/versions.env is newer, the build regenerates the manifest and merges your manual additions.

  • All existing commands and flags still work.

Migration scenarios

Scenario 1 — Fresh start

You are starting a new project.

opencenter-airgap init
$EDITOR config/versions.env
opencenter-airgap build
opencenter-airgap scan --repos    # optional: discover more components

Scenario 2 — Existing project, no customization

You have a stock components.yaml you have not modified.

cp config/components.yaml config/components.yaml.backup
opencenter-airgap build --force-regenerate
diff config/components.yaml.backup config/components.yaml

If the diff looks fine, delete the backup. Differences are usually limited to formatting and the _generated metadata block at the top.

Scenario 3 — Existing project with custom components

You added images, charts, or tools to components.yaml that are not in versions.env.

# Make versions.env newer than components.yaml so the merge runs.
touch config/versions.env

# Build merges generator output with your manual edits.
opencenter-airgap build

# Confirm the custom entries survived.
grep my-custom-image config/components.yaml

The merge is implemented in src/opencenter_build/component_manifest.py:merge_manifests(). It keeps any tool, repository, image, or chart from the existing manifest that the generator did not produce.

Scenario 4 — Move custom components into versions.env

You want to manage custom component versions in versions.env instead of components.yaml.

There is no built-in "promote to versions.env" command. The pattern:

  1. Add a version variable to config/versions.env: ` MYAPP_VERSION="v1.2.3" `

  2. Use opencenter-airgap add to add the component referencing the version. The CLI does not currently do ${MYAPP_VERSION} interpolation for add, so you still write the version explicitly. Treat versions.env as the documented source and re-run add whenever the version bumps.

If you maintain a fork, create_default_manifest() in component_manifest.py is where you would add custom mapping logic to make the version variable flow automatically into the generated manifest.

Scenario 5 — Keep the manual workflow

You prefer to maintain components.yaml by hand.

$EDITOR config/components.yaml
touch config/components.yaml      # ensure it is newer than versions.env
opencenter-airgap build           # uses your manifest as-is

The build only regenerates when versions.env is newer.

Verify

ls -l config/components.yaml config/versions.env
opencenter-airgap validate
opencenter-airgap build --clean

opencenter-airgap validate runs the schema check from src/opencenter_build/validation.py:ComprehensiveConfigValidator. It is the cheapest way to confirm the migrated state is consistent before a full build.

Pitfalls

  • components.yaml keeps regenerating. versions.env is newer than components.yaml. Either accept the regeneration (it preserves your edits) or touch config/components.yaml to flip the mtime back.

  • Custom components disappeared. You used --force-regenerate and the generator did not pick up the custom entry. Restore from git and re-run without the flag.

  • versions.env not found during build. Run opencenter-airgap init --force to drop in the default versions.env, then merge in your old values by hand.

Rollback

git log --all --full-history -- config/components.yaml
git checkout <commit> -- config/components.yaml
touch config/components.yaml
opencenter-airgap build

  • ../reference/component-manifest-schema.md[Component Manifest Schema] — every section and field.

  • ../reference/versions-env.md[versions.env Reference] — every variable in versions.env.

  • ../reference/cli-commands.md#build[CLI Commands → build] — --force-regenerate and friends.