Skip to content
Documentation
Authoring packages
Mirror package artifacts

Mirror package artifacts

nem author mirror downloads a catalog’s package archives (or sources, for buildFromSource packages), verifies their checksums, and publishes them to an OCI registry — where catalogs configured with artifacts: registry or artifacts: prefer-registry download them from.

nem author mirror ghcr.io/org/nem-catalog               # mirror ./
nem author mirror ghcr.io/org/nem-catalog ./catalog      # explicit dir

The catalog directory defaults to the current directory.

What happens

  1. Every pkgs/<name>/pkg.yaml is parsed and linted offline. Lint findings abort the run unless you pass --force.

  2. By default, every package’s latest version is selected — the same version nem use <pkg> would install.

  3. For each selected package, the archive (or source) is downloaded and verified against the manifest’s verify block, exactly as at install time. Anything that fails verification is never published.

  4. Verified artifacts are pushed to the registry:

    • Archives to <registry-base>/archives/<pkg>:<version>, one entry per platform.
    • Sources to <registry-base>/sources/<pkg>:<version>.

    So a mirror’s contents can be audited, pushed manifests are annotated with the package name (org.opencontainers.image.title), version (org.opencontainers.image.version), and the upstream URL the artifact was downloaded from (org.vi-dev.nem.upstream.url). Pushes are deterministic — no timestamps — so the same artifact always produces the same digest.

Selecting packages and versions

Restrict the run with --pkg, repeatable, optionally pinned to a version:

nem author mirror ghcr.io/org/nem-catalog --pkg kubectl --pkg helm@3.15.0

Platforms

Archives default to linux/amd64,linux/arm64,darwin/amd64,darwin/arm64. Override with --platforms:

nem author mirror ghcr.io/org/nem-catalog --platforms linux/amd64,linux/arm64

Sources are platform-independent, so --platforms doesn’t apply to them.

If an upstream asset is missing for one platform (some tools don’t ship every OS/arch), that platform is skipped with a warning and the rest are still mirrored. A package whose platforms all fail to fetch is reported as failed, without aborting the rest of the run.

Dry run

--dry-run resolves versions and reports what would be mirrored, without downloading or pushing anything:

nem author mirror ghcr.io/org/nem-catalog --dry-run

Idempotence

Mirroring is incremental: a package version whose <pkg>:<version> tag already exists in the registry is skipped and reported, so re-running nem author mirror only pushes what’s missing. There’s no --repush/overwrite flag — to force a version to be re-mirrored, delete its tag registry-side first, so drift is never silent.

A pkg.yaml whose archive/source block already declares a relative oci: fetch is skipped entirely: that artifact already lives in the target registry.

Consuming mirrored artifacts

Point a catalog at the mirror with artifacts: registry or artifacts: prefer-registry:

nem catalog add oci team ghcr.io/org/nem-catalog:v1 --artifacts registry

See Working with catalogs and Catalog for the consumer side.

Publish a catalog