Resolver Configuration

This page is the technical reference for OCM resolver configuration. For a high-level introduction, see OCM Resolvers.

Configuration File

Resolvers are configured in the OCM configuration file. By default, the CLI searches for configuration in $HOME/.ocmconfig. You can also specify a configuration file explicitly with the --config flag.

For more information about the OCM configuration file, see .ocmconfig documentation.

The resolver configuration uses the type resolvers.config.ocm.software/v1alpha1 inside a generic OCM configuration type:

type: generic.config.ocm.software/v1
configurations:
  - type: resolvers.config.ocm.software/v1alpha1
    resolvers:
      - repository:
          type: OCIRepository/v1
          baseUrl: ghcr.io
          subPath: my-org/components
        componentNamePattern: "example.com/services/*"
        versionConstraint: ">=1.0.0 <2.0.0"

Config Schema

The resolver configuration is defined by the resolvers.config.ocm.software/v1alpha1 type in the OCM specification.

FieldTypeRequiredDescription
typestringYesMust be resolvers.config.ocm.software/v1alpha1.
resolversarrayNoList of resolver entries.

Resolver Entry Schema

FieldTypeRequiredDescription
repositoryobjectYesAn OCM repository specification (must include a type field).
componentNamePatternstringNoGlob pattern for matching component names. If omitted, the resolver matches all components.
versionConstraintstringNoSemver constraint for matching component versions. If omitted, the resolver matches all versions.

Repository Types

The repository field accepts any OCM repository specification. The most common types are:

repository:
  type: OCIRepository/v1
  baseUrl: ghcr.io
  subPath: my-org/components
FieldRequiredDescription
typeYesRepository type. Must be OCIRepository/v1.
baseUrlYesRegistry host and optional port (e.g., ghcr.io, localhost:5000).
subPathNoRepository prefix path within the registry.
repository:
  type: CommonTransportFormat/v1
  filePath: /path/to/ctf-archive
FieldRequiredDescription
typeYesRepository type. Accepted values include CommonTransportFormat/v1 and the short form CTF/v1.
filePathYesPath to the CTF archive file or directory.
accessModeNoAccess mode: readonly, readwrite, or create.

Component Name Patterns

Each resolver entry can include a componentNamePattern field that uses glob patterns to filter for certain component names. Only components matching the pattern will be routed to that repository.

Supported glob patterns:

PatternMatches
example.com/services/*Any component directly under example.com/services/
example.com/core/**Any component under example.com/core/ or its subpaths
*All components (wildcard catch-all)

Pattern syntax:

  • * — Matches any sequence of characters within a path segment
  • ** — Matches any sequence of characters in subpath segments
  • ? — Matches any single character
  • [abc] — Matches any character in the set (a, b, or c)
  • [a-z] — Matches any character in the range

For more information on the supported glob syntax, see the glob package documentation.

Version Constraints

Each resolver entry can include a versionConstraint field that uses semver constraints to filter for certain component versions. Only components with versions satisfying the constraint will be routed to that repository.

Supported constraint syntax:

ConstraintMatches
>=1.0.0 <2.0.0Versions from 1.0.0 (inclusive) up to but not including 2.0.0
^1.2.0Compatible with 1.2.0 (>=1.2.0 <2.0.0)
~1.2.0Approximately 1.2.0 (>=1.2.0 <1.3.0)
1.2.3Exactly version 1.2.3

Multiple space-separated constraints are combined with AND logic (e.g., >=1.0.0 <2.0.0 means both must be satisfied).

For more information on the supported semver constraint syntax, see the Masterminds/semver documentation.

Validation

Both componentNamePattern and versionConstraint are validated when the configuration is loaded. If a resolver entry contains an invalid glob pattern or an unparseable semver constraint, the configuration will fail to load with an error describing the offending entry.

Backward Compatibility

The versionConstraint field is optional. Resolver entries that omit it continue to work exactly as before — they match any component version (or no version at all). Existing configurations that do not use versionConstraint require no changes.

Resolver Evaluation Order

Resolvers are evaluated in the order they are defined. The first matching resolver wins. Place more specific patterns before broader ones.

This is especially important when mixing constrained and unconstrained resolvers for the same component pattern. Resolvers with a versionConstraint should be listed before unconstrained catch-all entries, otherwise the catch-all matches first and the version constraint is never evaluated:

resolvers:
  # constrained entries first
  - repository: ...
    componentNamePattern: "my-org/*"
    versionConstraint: ">=2.0.0"
  # unconstrained catch-all last
  - repository: ...
    componentNamePattern: "my-org/*"
  • OCM Resolvers — High-level introduction to resolvers
  • Working with Resolvers Tutorial — Hands-on walkthrough for setting up resolvers
  • [How to Resolve Components Across Multiple Registries]
  • (/docs/how-to/resolving-components-across-multiple-registries/) — Recipe for multi-registry resolution
  • Migrate from Deprecated Resolvers — Replace deprecated fallback resolvers with glob-based resolvers
Prev
Configure Credentials for Signing
Next
Resolvers