Title here
Summary here
Resource Repositories
This page is the technical reference for built-in resource repositories. For an introduction to what resource repositories are and why they exist, see Concept: Resource Repositories.
OCI Resource Repository
Handles OCI artifacts stored in OCI-compliant registries.
Supported Access Types
| Access Type |
|---|
OCIImage/v1 |
Capabilities
| Operation | Supported |
|---|---|
| Download | Yes |
| Upload | Yes |
| Digest Processing | Yes |
Credential Resolution
The credential consumer identity is derived from the imageReference field in the access specification. The registry
hostname is extracted from the image reference to construct an identity of type OCIRegistry.
Example: For a resource with access imageReference: ghcr.io/acme/myapp:1.0.0, the resolved identity is:
| Attribute | Value |
|---|---|
type | OCIRegistry |
hostname | ghcr.io |
scheme | https |
This identity is then matched against configured consumers in the credential system. See Credential Consumer Identities: OCIRegistry for matching rules.
Download Behavior
Downloads the complete OCI artifact (manifest and layers) from the registry. The returned blob represents the artifact in its OCI format.
Upload Behavior
Pushes an OCI artifact to the target registry. The resource descriptor is updated with the repository-specific access information (e.g., the final image reference with digest) after upload.
Digest Processing
The OCI resource repository also implements digest processing. When constructing a component version with a by-reference resource, OCM queries the registry to resolve and verify the artifact’s digest, ensuring the resource descriptor is pinned to an immutable reference.
Helm Resource Repository
Handles Helm charts stored in HTTP/HTTPS-based chart repositories.
Supported Access Types
| Access Type |
|---|
Helm/v1 |
Capabilities
| Operation | Supported |
|---|---|
| Download | Yes |
| Upload | No |
| Digest Processing | Yes |
Upload is not supported because traditional Helm chart repositories are read-only HTTP servers that serve a static
index.yaml and packaged chart archives. There is no standardized upload API.
For Helm charts stored in OCI registries, use the OCI resource repository with an OCIImage/v1 access type instead.
Credential Resolution
The credential consumer identity is derived from the helmRepository field in the access specification. The identity
type is HelmChartRepository.
Example: For a resource with helmRepository: https://stefanprodan.github.io/podinfo:
| Attribute | Value |
|---|---|
type | HelmChartRepository |
hostname | stefanprodan.github.io |
scheme | https |
path | podinfo |
If the resource has no helmRepository (a local chart embedded via input), no credential identity is returned — local
charts do not require remote authentication.
See [Credential Consumer Identities: HelmChartRepository] (/main/docs/reference/credential-consumer-identities/#helmchartrepository) for matching rules.
Download Behavior
Downloads the Helm chart (and optional .prov provenance file) from the remote repository. The chart is packaged into a
tar archive and returned as an in-memory blob.
The helmChart and helmRepository fields from the access specification are combined to construct the full chart
reference used for download.
Digest Processing
The Helm digest processor resolves chart digests from the remote repository. For HTTP/HTTPS repositories it downloads
the index.yaml and extracts the digest for the specified chart and version. For OCI-based Helm repositories it
resolves the OCI manifest digest via the registry API.
Wget Resource Repository
Handles resources served over plain HTTP or HTTPS.
Supported Access Types
| Access Type |
|---|
Wget/v1 |
Capabilities
| Operation | Supported |
|---|---|
| Download | Yes |
| Upload | No |
| Digest Processing | Yes |
Upload is not supported because a plain HTTP endpoint has no standardized write API. The transfer downloads the content
and stores it as a LocalBlob/v1 in the target repository, regardless of the requested upload type.
Credential Resolution
The credential consumer identity is derived from the url field in the access specification. The identity type is
Wget.
Example: For a resource with url: https://downloads.example.com/myapp/1.0.0/myapp.tar.gz:
| Attribute | Value |
|---|---|
type | Wget |
hostname | downloads.example.com |
scheme | https |
path | myapp/1.0.0/myapp.tar.gz |
The Wget/v1 input type derives the identity the same way,
so one consumer entry covers construction and later downloads.
See Credential Consumer Identities: Wget for matching rules.
Download Behavior
Performs the request described by the access specification (verb, header, body, noRedirect) and returns the
response body as a file-backed blob. Only 2xx responses are accepted. The body is streamed to a file under the
tempFolder of the filesystem.config.ocm.software/v1alpha1 configuration type rather than buffered in memory, and
there is no size limit by default. The media type of the blob is taken from mediaType, falling back to the response
Content-Type and then to application/octet-stream.
Request timeouts, retries, and per-host settings come from the HTTP client configuration.
Digest Processing
The Wget digest processor downloads the referenced content and hashes it with SHA-256, using the
genericBlobDigest/v1 normalisation. When the resource already carries a digest, the computed value is verified against
it and a mismatch fails the operation. Because the digest is computed over the fetched bytes, a URL whose content
changes will not verify against a previously recorded digest.
A resource can carry a digest before it has ever been fetched: setting the optional digest field on the resource in
component-constructor.yaml turns the recorded value into an assertion, so ocm add cv fails rather than recording
whatever the server returned. See
Tutorial: Work with HTTP Resources.
S3 Resource Repository
Handles resources stored as a single object in an S3 or S3-compatible bucket (AWS S3, MinIO, Ceph RGW, Cloudflare R2).
Supported Access Types
| Access Type |
|---|
S3/v2 |
Capabilities
| Operation | Supported |
|---|---|
| Download | Yes |
| Upload | No |
| Digest Processing | Yes |
The repository supports download only, the same as OCM v1. OCM never writes an object into a bucket, so an upload
never creates an S3/v2 access specification.
Credential Resolution
OCM derives the credential consumer identity from bucketName, objectKey and the optional endpoint of the access
specification. The identity type is S3.
Example: A resource sets bucketName: acme-artifacts and
objectKey: datasets/reference/1.0.0/reference.parquet, and sets no endpoint:
| Attribute | Value |
|---|---|
type | S3 |
path | acme-artifacts/datasets/reference/1.0.0/reference.parquet |
An endpoint adds its scheme, hostname and port. AWS S3 adds no hostname, because it is the default target. The
S3/v2 input type derives the identity the same
way, so one consumer entry covers the construction and the later downloads.
Credentials are optional. If no consumer entry matches, the AWS default credential chain applies: environment variables, the shared AWS config, and IAM instance or task roles.
See Credential Consumer Identities: S3 for matching rules.
Download Behavior
Sends a GetObject request for the bucket and the key of the access specification. If version is set, the request
reads that version. OCM streams the body to a file under the tempFolder of the
filesystem.config.ocm.software/v1alpha1 configuration type. It does not hold the body in memory, and there is no size
limit by default. The media type of the blob comes from mediaType. If mediaType is empty, OCM uses the
Content-Type of the object, and then application/octet-stream.
Requests go through the shared OCM HTTP client, so timeouts, TLS settings and per-host overrides come from the
HTTP client configuration. The AWS SDK does the retries. It retries
the whole operation and signs each attempt again. The configured retry.maxRetries sets its attempt count. The SDK
resolves the request host for AWS, so a per-host retry entry takes effect only for a custom endpoint. For AWS, the
global setting applies.
Digest Processing
The S3 digest processor downloads the object and hashes it with SHA-256. It applies the genericBlobDigest/v1
normalisation. It does not use the S3 ETag, because the ETag is not a whole-object hash for a multipart upload. If
the resource already has a digest, OCM compares the computed digest with it. A difference fails the operation.
Digest processing also pins the access specification to the object version that it read, so a later read gets the same
object. On an unversioned bucket, S3 reports the placeholder null. It pins nothing, and OCM never writes it back.
See
Input and Access Types: Object versions and integrity.
GitHub Resource Repository
Handles source archives of a pinned commit in a GitHub (or GitHub Enterprise) repository.
Supported Access Types
| Access Type |
|---|
GitHub/v1 |
Capabilities
| Operation | Supported |
|---|---|
| Download | Yes |
| Upload | No |
| Digest Processing | Yes |
Upload is not supported: the GitHub/v1 access type is a read-only source reference. Content is pushed to GitHub
through git, not through OCM.
Credential Resolution
The credential consumer identity is derived from the repoUrl field in the access specification. The identity type is
GitHubRepository.
Example: For a resource with repoUrl: https://github.com/open-component-model/ocm:
| Attribute | Value |
|---|---|
type | GitHubRepository |
hostname | github.com |
scheme | https |
path | open-component-model/ocm |
The identity is derived from repoUrl on GitHub Enterprise hosts too. Credentials are optional: without them requests
are anonymous, subject to GitHub’s per-IP rate limit, and private repositories answer 404. When credentials resolve,
their token property (a GitHub or GitHub Enterprise access token) authenticates against the GitHub REST API.
apiHostname does not change the consumer identity. When the REST API lives on a host other than the repository, the
identity still carries the repoUrl host, so configure the consumer for that host rather than for apiHostname. The
resolved token is then sent to the apiHostname host.
See Credential Consumer Identities: GitHubRepository for matching rules.
Download Behavior
Downloads the source archive of the commit pinned in the access via the GitHub REST API. The archive is returned as an in-memory gzipped tar blob.
Digest Processing
If the access has only a ref, the GitHub digest processor resolves it to a commit and writes that commit onto the
resource. This works like an OCI tag that is pinned to a digest. It then downloads the archive at that commit and
hashes it: SHA-256 over the archive bytes, normalisation genericBlobDigest/v1.
If the access already has a commit, the ref is not resolved again. A branch can move on, or be deleted after a merge,
and that must not break a component version that has not changed.
The digest is checked on both paths. If the resource already declares one, the computed value must match it. The hash and normalisation algorithms are only compared when they are set: an empty field is filled in with the computed value.
External Resource Repositories (Plugins)
External plugins declare supported access types in their capability specification and implement the same three operations (resolve credential identity, download, upload) over the plugin protocol. Once installed, OCM routes requests for matching access types to the plugin automatically.
See Concept: Plugin System for details on building and installing plugins.
Related Documentation
- Concept: Resource Repositories: why resource repositories exist and how they fit into OCM
- Reference: Input and Access Types: access type specifications handled by resource repositories
- Reference: Credential Consumer Identities: identity types and matching rules for credential resolution
- Concept: Transfer and Transport: how resource repositories enable artifact transfer