Migrate Legacy Credentials

Goal#

Update a legacy OCM .ocmconfig file to use modern field names and optional typed credentials. Most fields work unchanged in the new OCM; this guide covers the renamed field (pathprefix → path) and the optional migration to typed credentials.

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. pathprefix matched the prefix and every path below it; path is a glob pattern, so append /** to cover every path below the prefix:

       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 only matches the exact path open-component-model, not open-component-model/my-repo. open-component-model/** matches any depth below the prefix but not open-component-model itself, and open-component-model/* matches a single segment. To also match the prefix itself, use "{open-component-model,open-component-model/**}" (quoted: unquoted, YAML reads {…} as a mapping). For the full pattern syntax, see Credential Consumer Identities: Path Patterns.

   The new OCM still reads pathprefix, converts it into the equivalent path pattern (pathprefix: open-component-model becomes path: "{open-component-model,open-component-model/**}"), and logs a warning that points to this guide. If an entry sets both, path wins. Legacy OCM picked the entry with the longest matching pathprefix; the new OCM does not rank matching entries, so avoid overlapping entries with different credentials.

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. Migrate to typed credentials

   Replace Credentials/v1 with the typed equivalent for your credential type. Typed credentials use flat top-level fields instead of a nested properties: map and are validated at parse time.

   For OCI registries, replace:

           credentials:
             - type: Credentials/v1
               properties:
                 username: my-user
                 password: my-token

   with:

           credentials:
             - type: OCICredentials/v1
               username: my-user
               password: my-token

   OCICredentials/v1 also supports accessToken and refreshToken for token-based auth. For all built-in typed credential types and their fields, see Reference: Credential Types.

   Credentials/v1 continues to work unchanged — it is an alias for DirectCredentials/v1. You only need this step if you want field validation and cleaner configuration.

4. Verify

   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: OCICredentials/v1
               username: my-user
               password: my-token
       repositories:
         - repository:
             type: DockerConfig/v1
             dockerConfigFile: "~/.docker/config.json"

   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 the path and pathprefix values of your consumer entries. Both are compared with whole path segments: pathprefix: org/repo does not match org/repo.git.

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
• Reference: Credential Types - All built-in typed credential types and their fields