[FEATURE] Support OCI registries for publishing and consuming APM packages

[vlsi]

Is your feature request related to a problem? Please describe.
APM distribution is currently centered around Git-based package sources and local packed artifacts. That works well for source-centric workflows, but it is a poor fit for enterprise environments that standardize on OCI registries for artifact storage, promotion, access control, and mirroring.

In particular, I would like to consume APM packages from OCI in apm.yml, either alongside or instead of current Git-based dependencies. I also want this to work without hard-coding a specific registry host into package definitions, since enterprise deployments often rely on proxies, mirrors, or internal registry indirection.

Describe the solution you'd like

Add native OCI registry support for APM packages and bundles.

Specifically, I would like:

• a way to publish APM packages or packed bundles to OCI registries
• a way to install or unpack APM packages directly from OCI
• digest-pinned installs for reproducibility
• standard OCI authentication support
• a way to declare OCI-based dependencies in apm.yml
• a host-agnostic way to reference OCI packages in apm.yml, so package identity can be separated from the concrete registry host

Ideally, OCI dependencies could be used side by side with existing Git dependencies, or as an alternative dependency model where appropriate.

Describe alternatives you've considered

Current alternatives are not a full replacement:

• continuing to use Git repositories as the package source
• using apm pack plus external CI artifact handling
• relying on registry/proxy setups for Git/VCS access

These approaches help, but they are not equivalent to native OCI support. They do not provide a clean OCI-based dependency model in apm.yml, and they do not address the need for host-independent package references that work well with enterprise proxy and mirroring setups.

Additional context

This would be especially useful for organizations using GHCR, ACR, ECR, Harbor, Artifactory, Nexus, or similar registry infrastructure.

A key requirement from my perspective is that OCI references in apm.yml should not require hard-coding a public or environment-specific host such as ghcr.io. A logical reference, alias-based model, or config-resolved OCI source would be more suitable for enterprise use.

[danielmeppiel]

Triaged under the new portability/security/governance roadmap (see #116).

Thanks @vlsi -- this is a well-scoped feature ask and the
host-agnostic reference requirement is exactly the kind of detail
that makes or breaks enterprise adoption.

Triage decision

needs-design -- direction is right (OCI is a natural fit for the
Portable pillar and a frequent enterprise ask), but several design
calls have to land before code can:

1. Reference syntax in apm.yml. Logical alias vs concrete OCI
   reference vs both, plus how apm-policy.yml resolves an alias to
   a concrete registry host (per-environment override, mirror
   indirection).
2. Identity primitive. Today APM pins by Git commit SHA; for OCI
   the equivalent is the manifest digest. The lockfile schema needs
   an OCI-aware entry shape that records both the logical reference
   and the resolved digest.
3. Auth model. OCI registries use Bearer / Basic / token-exchange
   patterns; we need this to flow through AuthResolver rather than
   spawning a parallel credential path.
4. Coexistence with Git deps. Side-by-side mode is the user ask;
   the resolver and lockfile have to handle a mixed graph cleanly.

This is large enough to warrant its own design doc + APM Review Panel
pass before any code lands.

Proposed labels

theme/portability
area/distribution
type/feature
status/needs-design

Milestone

null -- no milestone until the design has been ratified.

Suggested next action

If you have a preferred reference syntax or alias-resolution model in
mind, drop a sketch in the comments and we will fold it into the
design doc. Otherwise we will draft one and link it back here for
review.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

OCI references in apm.yml need to read like Git references already
do -- short, readable, and easy to grep. The host-agnostic ask means
the dependency identifier should not embed ghcr.io or acr.io
literally; apm-policy.yml is the right place to map a logical name
to a concrete host. CLI surface implications: apm install,
apm pack, and the publish path all need parallel OCI behaviour, and
apm install --help should make the reference syntax discoverable.

Supply Chain Security Expert -- Risk-Surface Reviewer

OCI changes the integrity primitive: today the lockfile pins to a
Git SHA, tomorrow it pins to an OCI manifest digest. Both must be
fail-closed. We must verify the digest matches what the registry
actually returned and refuse silent fallback if the digest is
missing or the registry is unreachable. Auth must route through
AuthResolver (no parallel os.getenv paths). Promotes the design
from area/distribution alone to also touch area/lockfile and
implicitly the theme/security story (digest pinning is the
integrity guarantee). Marketplace name resolution should NOT be
extended to OCI references without a separate design pass --
typosquatting + dependency confusion attack surface widens
substantially with a public OCI registry.

OSS Growth Hacker -- Contributor-Tone Reviewer

Author has 2 prior interactions on microsoft/apm; treat as a
relatively-new contributor. Tone should be welcoming, name the
concrete next step (sketch a design or we draft one), and avoid
internal jargon. The reply does that and explicitly invites their
input on the reference syntax.

APM CEO -- Triage Arbiter

OCI is on the strategic path for enterprise adoption and reinforces
the Portable pillar. Holding at needs-design because shipping it
with the wrong reference syntax or a weak integrity primitive would
be worse than not shipping it at all. Primary
theme/portability, secondary security implications captured in the
design lane. No milestone until the design lands.

[danielmeppiel]

Hi @vlsi, thanks for logging this. You are pointing at a real enterprise need. I agree with the problem, but I do not think OCI should become the package protocol itself. APM is Git-native by design, and we want to keep package identity, dependency resolution, and source of truth separate from artifact transport. Specially in this early stage for APM.

Our approach is to support OCI-compatible storage and enterprise proxy patterns where they fit, while keeping apm.yml clean and source-centric. That lets us preserve reproducibility and portability without introducing a second, conflicting dependency model.

The Artifactory proxy support is groundwork that should let APM work with OCI in the same way npm does. And my stance today is that ensuring that part works should be the first step here.

[vlsi]

I agree that OCI should not become the package identity model or the source of truth for APM.
Let me clarify the request: I am not suggesting that apm.yml should hard-code OCI references such as ghcr.io/org/pkg:tag, nor that OCI should replace Git-native package identity. My main concern is that the dependency declaration should remain stable regardless of whether a package is fetched from Git, an internal mirror, Artifactory/Nexus/Harbor, or another OCI-compatible registry.

In other words, I would prefer a model where apm.yml declares a logical package dependency, and environment-specific policy/config resolves that logical package to a concrete source:

dependencies:
  - package: acme/sre-troubleshooting
    version: 1.2.3

Then policy/config could resolve acme/sre-troubleshooting to Git in one environment, GHCR in another, or an internal OCI registry/proxy in enterprise deployments. The lockfile would still record the concrete resolved identity, for example Git commit SHA or OCI manifest digest.

So I think we are aligned on keeping package identity separate from artifact transport. The missing piece I am asking for is: OCI should be a first-class transport/storage backend that can participate in dependency resolution and lockfile pinning, without forcing apm.yml to embed registry-specific hosts.

---

Could you clarify what you mean by “Artifactory proxy support should let APM work with OCI in the same way npm does”?

Frankly, I don't think npm packages could be shipped with OCI. It does not sound like npm/yarn/pnpm support fetching packages from OCI.