Migrate Legacy Credentials

Goal#

Migrate an existing legacy OCM .ocmconfig file so it works with the new OCM.

Prerequisites#

• OCM CLI installed
• An existing .ocmconfig file from legacy OCM

Steps#

Suppose you have the following legacy config in $HOME/.ocmconfig:

type: generic.config.ocm.software/v1
configurations:
  - type: credentials.config.ocm.software
    consumers:
      - identity:
          type: OCIRegistry
          hostname: ghcr.io
          pathprefix: open-component-model
        credentials:
          - type: Credentials/v1
            properties:
              username: my-user
              password: my-token
    repositories:
      - repository:
          type: DockerConfig/v1
          dockerConfigFile: "~/.docker/config.json"

The following steps walk you through each change needed to make this config work with the new OCM.

1. Change pathprefix to path with a glob pattern

   The field for matching repository paths was renamed from pathprefix to path. Because pathprefix matched any path starting with the given prefix, you need to append a glob pattern (/*) to preserve the same matching behavior:

       consumers:
         - identity:
             type: OCIRegistry
             hostname: ghcr.io
             path: open-component-model/*  # was: pathprefix: open-component-model

   path does not do prefix matching — path: open-component-model would only match the exact path open-component-model, not open-component-model/my-repo. Use open-component-model/* to match any single segment after the prefix, or open-component-model/*/* for two levels.

2. Change identity to identities (optional)

   The new OCM still accepts the singular identity field, so this step is optional. However, switching to identities (a list) lets you share one credential across multiple registries. See Multi-Identity Credentials for details.

       consumers:
         - identities:  # was: identity (now a list)
             - type: OCIRegistry
               hostname: ghcr.io
               path: open-component-model/*

3. Keep everything else as-is

   The following parts of your legacy config work unchanged in the new OCM:

   • OCIRegistry consumer identity type (unchanged)
   • Credentials/v1 type and properties field
   • DockerConfig/v1 repository entries
   • dockerConfigFile and dockerConfig fields
   • Config file locations ($HOME/.ocmconfig, $OCM_CONFIG)

   Your migrated config now looks like this:

   type: generic.config.ocm.software/v1
   configurations:
     - type: credentials.config.ocm.software
       consumers:
         - identities:
             - type: OCIRegistry
               hostname: ghcr.io
               path: open-component-model/*
           credentials:
             - type: Credentials/v1
               properties:
                 username: my-user
                 password: my-token
       repositories:
         - repository:
             type: DockerConfig/v1
             dockerConfigFile: "~/.docker/config.json"

4. Verify

   Run any OCM command that requires authentication:

   ocm get cv ghcr.io/my-org/my-component

   If you get unknown credential repository type, you may be using a repository type not yet supported in the new OCM (HashiCorpVault/v1, NPMConfig/v1, GardenerConfig/v1). Remove the unsupported entry or stay on legacy OCM until support is added.

   If you get 401 Unauthorized, check that you renamed pathprefix → path (with a glob pattern) in all consumer entries.

Next Steps#

• How-To: Configure Credentials for Multiple Registries - Set up credentials for multiple registries
• Tutorial: Credential Resolution - Learn how OCM resolves credentials step-by-step

Related Documentation#

• Concept: Credential System - Learn how the credential system automatically finds the right credentials for each operation