Change an OCI package without ConfigHub

Generated at: 2026-07-30T12:38:02.000Z UTC · source: committed helm-expt evidence for this rendered repository document.

UNOFFICIAL/EXPERIMENTAL.

Use this path when you already have an OCI package containing Kubernetes objects and need to make a small, reviewable change. You do not need a ConfigHub account, ConfigHub Server, or a Kubernetes cluster.

The command pulls the package, changes one named field, runs checks, and writes a new local OCI image. It records the input digest, the old and new values, and the check results inside the output image. It then pulls the new image back and compares the objects and records.

This is useful before ConfigHub as well as beside it. A team can run the command locally or in CI, inspect the result, and decide later whether to publish the image, upload it to ConfigHub, or deploy it with an existing controller.

Before you change it

First identify what the OCI contains:

npm run oci:inspect -- oci://REGISTRY/REPOSITORY:TAG

The OCI inspection guide explains the package roles. oci:transform accepts a literal Kubernetes configuration OCI. A Helm source chart or cub installer package must be rendered first.

Change one field

This tested example starts with five reviewed NGINX objects and changes the Deployment from three replicas to four:

npm run oci:transform -- \
  oci://europe-west1-docker.pkg.dev/nth-fort-499605-q5/helm-expt/byo-nginx-ai-values@sha256:34af6a50b952d1a168a5cad614ef47f652cf44b11806a93bf6cc7a79c6e9c683 \
  --object Deployment/nginx \
  --namespace nginx \
  --field spec.replicas \
  --value 4 \
  --output oci-layout:./nginx-replicas-4:reviewed

Anonymous registry access is the default. The command gives ORAS an empty credential file. Use --registry-config FILE only when the input is private.

--value accepts JSON values. Numbers, booleans, strings, arrays, and objects are supported. The field must already exist. The command will not silently add an unknown path, add or remove Kubernetes objects, or change more than the one field you named.

What the output contains

The new OCI image has four readable files:

File	Purpose
`manifests/release-objects.yaml`	The complete changed Kubernetes object set.
`records/source.json`	The input reference, resolved digest, object hash, and any context you supplied.
`records/change.json`	The object, field, old value, new value, and before/after object hashes.
`records/checks.json`	The decision and every pass, warning, or failure.

If the input already contains companion records, they are retained under records/input/. A second change therefore keeps the records from the first change instead of replacing them.

The current checks reject malformed objects, duplicate object identities, obvious placeholder values, and a change that affects anything outside the named field. They also report unpinned container images, missing probes, and external Secret references. CRDs, Jobs, and Helm hook annotations produce a lifecycle warning so that install order and execution still receive a separate review.

The NGINX example passes with one warning because the target must provide the nginx/ai-provider-credentials Secret. The warning is stored in the output image.

What happens next

The command creates a local OCI image layout. It does not publish or deploy it. From there you can:

inspect the changed YAML and records;
push the image to a registry with an authenticated tool;
upload the literal configuration to ConfigHub as a base variant;
give a compatible deployment bundle to Argo CD or Flux; or
discard it and leave the input unchanged.

These are separate actions because they have different permissions and consequences.

Proof and limits

The anonymous OCI-to-OCI receipt records the public input digest, exact replica change, check results, output digest, and pull-back comparison.

That reviewed output is also published as a permanent public example:

oci://europe-west1-docker.pkg.dev/nth-fort-499605-q5/helm-expt/nginx-replicas-4@sha256:aa58e2a9d120d09f029fdef80596225f8c44d0aa629b18766fe8b6694659f518

Read the publication and ConfigHub import summary for the recorded digest, anonymous pull-back, companion-record checks, and exact ConfigHub object comparison. A separate GitHub Actions job repeats the public source pull with no ConfigHub credentials.

Direct ConfigHub import of an OCI with companion JSON records needs the fix in confighub/sdk PR #11. The fix is merged but newer than cub v0.2.5. Until the next cub release, extract manifests/release-objects.yaml before upload.

The proof does not claim cluster admission, controller reconciliation, workload health, or a signed provenance chain. Your own command still creates a local OCI layout until you publish it deliberately.