When Argo CD deploying from an OCI registry makes sense
If your platform team already stores container images and Helm charts in a registry and wants one artifact store to feed delivery, an OCI source may fit better than Git. With a Git source, Argo CD watches a repository and renders manifests from its content. With an OCI source, Argo CD pulls an OCI artifact from a registry and renders it the same way, so the registry becomes the place where a versioned deployment unit is published and consumed. That shifts the question from where the manifests live to which system is the system of record for release artifacts, and that is a decision to make before the first Application is created. The model suits teams that publish rendered manifests or charts as versioned artifacts from CI, and that want promotion to happen by moving a tag or digest rather than by merging to a branch. It also suits organizations whose registry already carries access control, replication and scanning policy that auditors review. Confirm with your security team whether the registry is already the approved store for release artifacts, because otherwise you will run two sources of truth. Git remains the simpler choice for teams that want pull request review of every manifest change and a commit history as the audit trail.
The OCI guide supports this path across the Argo CD releases that currently receive patches, so the choice does not depend on running a particular minor version. Check the Argo CD OCI guide against the exact version you deploy, because accepted layer media types and repository credential behavior are configuration details that you should test in your own environment before relying on them. Plan a proof of concept that pulls one artifact through the same registry access path your production clusters will use, including the credentials the repo-server will hold.
Choosing between Git and an OCI registry as the source
Git and an OCI registry can both feed Argo CD, and the choice shapes how changes are reviewed, how versions are pinned and who can publish what Argo CD deploys. The factors below are the ones teams usually weigh first, and each one has a question to settle in your own environment before you pick a source for a given application.
Release immutability and pinning
A Git source points at a branch, tag or commit that someone can move or rewrite, while an OCI artifact is addressed by a tag or digest that your registry policy can make immutable. Decide whether production should pin to a digest so that the manifests Argo CD syncs match exactly what was reviewed. Confirm whether your registry lets you block tag overwrites for the projects Argo CD reads from.
Existing registry governance
Many organizations already control image pushes, scanning and retention in a registry, and an OCI source lets Argo CD pull deployment artifacts through the same controls. Check whether your registry team will accept manifest artifacts alongside images, and who approves new repositories. If your registry is not yet governed this way, the Git path may need less new process.
Helm chart distribution
If your teams already publish Helm charts as OCI artifacts, reading them directly from the registry avoids a second chart repository. Argo CD needs a Helm repository credential with the enable-OCI setting and a path of . for OCI charts, so confirm that every chart you deploy is in a registry Argo CD can reach. Charts still stored in a classic Helm index or in Git follow a different credential and path pattern.
Signed and scanned artifacts
Neither source gives Argo CD a built-in signature check on its own, so the trust decision sits in your pipeline and registry. Ask whether artifacts are signed before they are pushed, whether your registry scans them, and whether a failed check can stop a sync. Make sure the registry you choose can enforce these checks before the artifact reaches Argo CD.
Who publishes the artifacts
With Git, developers and reviewers usually change manifests through pull requests, and the commit history records who changed what. With an OCI source, a CI job or release pipeline often pushes the artifact, so the audit trail moves to the pipeline and its credentials. Decide which identity may push, and confirm that push rights are as tightly held as merge rights in your Git hosting.
Single-layer and media type limits
An OCI artifact Argo CD reads must carry a single layer with an accepted media type, and any other type must be allowed explicitly on the repo-server. Packaging teams need to know this before they standardize on an artifact format, because a multi-layer bundle will not sync until it is repackaged or the allowed types are changed. Test one artifact end to end in a non-production cluster before you commit a whole team to the format.
Repository credential types and source settings
This table compares the oci credential type for native OCI artifacts with the Helm-over-OCI setup, which uses --type helm and --enable-oci without the oci:// prefix. Read each row as a setting you must get right before the first sync, since a mismatch usually shows up as a repository that fails to resolve rather than as a clear error. The main takeaway is that the credential type and the path value must match how the artifact was packaged.
| Setting | Native OCI artifact (oci type) | Helm chart over OCI (helm type) |
|---|---|---|
| Credential type | oci, registered for the repository URL | helm with --enable-oci, so Argo CD treats it as a Helm repository |
| URL form | Registry address with the oci:// prefix | Registry address without the oci:// prefix |
| Path value on the application | Directory or path inside the artifact that holds manifests | Must be '.' because the chart sits at the root of the artifact |
| Accepted layer media type | Single layer typed as an OCI image layer tar+gzip by default | Single layer typed as a CNCF Helm chart content tar+gzip by default |
| Other layer media types | Allowed only if added through the repo-server OCI layer media type setting | Allowed only if added through the same repo-server setting |
| Typical fit | Plain Kubernetes manifests or Kustomize output pushed as an artifact | Helm charts already published to a registry that Helm can pull |
| Common failure | Artifact has more than one layer, which Argo CD rejects | Path set to a subfolder, so the chart is not found |
| What to confirm | Packaging tool and layer types with your registry team before the first sync | Chart push method and the exact media type used in your pipeline |
Which artifact layer types Argo CD accepts by default
Argo CD accepts an OCI artifact as an application source only when the artifact has a single layer whose media type is on the accepted list. By default that list holds two types: application/vnd.oci.image.layer.v1.tar+gzip for generic OCI artifacts holding a compressed tar of manifests, and application/vnd.cncf.helm.chart.content.v1.tar+gzip for Helm charts pushed to an OCI registry. The single-layer rule matters when you publish: an artifact with several layers, or a layer with any other media type, will fail to load in the repo-server even if the registry accepts the push. Before you wire a registry into Argo CD, push one test artifact from your pipeline and confirm its layer count and media type with your registry's inspection tooling.
The accepted list is set on the repo-server through the ARGOCD_REPO_SERVER_OCI_LAYER_MEDIA_TYPES environment variable, which extends the defaults. Widening it lets Argo CD read artifacts built by tools that use their own media types, but it also means the repo-server will unpack content it previously refused. Because the repo-server runs Helm and Kustomize on whatever it reads, every added media type expands the set of artifacts that can reach that process. Keep the list as short as your publishing tools allow, and treat any change to it as a change to the repo-server's trust boundary that goes through the same review as a new repository credential. Confirm the exact variable name and value format against the Argo CD OCI guide for the Argo CD version you run, since the repo-server configuration is version specific.
How to set up an OCI application source step by step
This sequence takes a team from an empty registry project to an Argo CD Application that syncs manifests or a Helm chart pulled from an OCI registry, with a check at each stage so failures surface where they start.
Prepare the registry project and access
The platform team creates a project in the registry for application artifacts, then creates a robot or service account that can pull from that project and a separate account that can push from the build pipeline. Keep Argo CD on the pull-only account. Confirm the registry is reachable from the Argo CD repo-server network path and that TLS trust for the registry is in place. Check: a plain pull with the read-only account succeeds from a machine on the same network as the repo-server, and a push attempt with that account is refused.
Package manifests or a Helm chart
The application team decides what the artifact contains: either a directory of rendered Kubernetes manifests or a packaged Helm chart. Argo CD reads a single layer per OCI artifact, so bundle the files into one archive before pushing. Use the media type Argo CD accepts by default for plain content or for Helm charts, and avoid mixing both in one artifact. Check: list the archive contents locally and confirm the top-level layout matches the path you plan to set in the Application.
Push the artifact with ORAS
The pipeline pushes the packaged content to the registry with ORAS, setting the artifact type and the layer media type explicitly so the repo-server accepts it. Tag each build with an immutable version, such as a commit digest or release number, and keep a moving tag only for convenience. Check: the registry UI or an ORAS pull of the new tag returns the same file list you packaged, and the layer media type matches the accepted value.
Register the repository credential as a Secret
Define the registry as an Argo CD repository in a Kubernetes Secret labeled for repositories, because Argo CD 3.0 removed repository definitions from the argocd-cm ConfigMap. Use credential type oci for plain OCI artifacts. For a Helm chart published over OCI, use type helm with OCI enabled and omit the oci:// prefix from the URL. Store the password from the read-only account, never the push account. Check: the repository appears as connected in the Argo CD settings, and the Secret is applied in the Argo CD namespace only.
Define the Application with the correct path
Create the Application resource with the OCI repository URL, the tag or version to track, and the destination cluster and namespace. For plain manifests, set the path to the directory inside the artifact that holds the YAML. For an OCI Helm chart, the path must be a single dot, since the chart sits at the root of the artifact. Start with manual sync so the first reconciliation is reviewed. Check: the Application shows the expected resource list in the diff view before any sync is triggered.
Verify the first sync and the change path
Trigger the first sync and confirm the resources reach the Healthy and Synced state in the destination namespace. Then push a new artifact version and confirm Argo CD detects it and shows the change in the diff before applying it. Review the repo-server and application controller logs if the status stays Unknown or shows a media type or credential error. Check: the live objects in the cluster match the artifact version shown in the Application, and a failed test push produces a clear error in the Application status rather than silent drift.
Pushing manifests and charts to the registry with ORAS
The most common failure in an OCI-based pipeline is a pushed artifact that Argo CD cannot read, so the first rule is that the media type you push must match what the repo-server accepts. By default, Argo CD accepts an OCI artifact whose single layer uses application/vnd.oci.image.layer.v1.tar+gzip or application/vnd.cncf.helm.chart.content.v1.tar+gzip. Push manifests with ORAS using one of these layer types, and confirm the type on the stored artifact before any Application points at it. If your pipeline needs another type, it must be allowed on the repo-server through ARGOCD_REPO_SERVER_OCI_LAYER_MEDIA_TYPES, which is a platform change you should review like any other repo-server setting. Keep the artifact to one layer, because the single-layer rule is enforced at sync time and a multi-layer push can look valid in the registry while failing in Argo CD.
Tag each release artifact with the version the change board approves, and treat that tag as a label rather than the source of truth. Pin Applications to the digest of the artifact, not a mutable tag, so the content Argo CD syncs is the content your pipeline tested. Harbor can enforce immutability on tags in a project, which blocks overwriting a released tag, and that control is only as strong as the project settings you apply to the release repositories. Confirm these settings in your registry version's documentation before you rely on them, since behavior has changed across Harbor releases. Record the digest in your change record so an auditor or responder can trace which bytes were deployed.
Before relying on the pipeline, test the full path in a non-production cluster: push a known-good artifact, add the OCI repository credential with the oci type, sync an Application, then confirm the rendered output matches what you expect. Repeat the test with a deliberately wrong media type to confirm the failure is visible and that alerting catches it. For Helm charts published over OCI, test the path value of '.' and the Helm-over-OCI credential type together, since a mismatch there is a common source of confusing errors. Ask your registry team to confirm the replication and retention behavior of the destination registry, because an artifact that is cleaned up or replicated late will break a sync that worked in testing.
Security risks when Argo CD pulls from a registry
An OCI artifact reaches the cluster through credentials, a repo-server that renders its contents, and a publish path that someone controls. Each risk below maps to a control you can check in your own environment before the first sync.
Registry credentials stored in cluster Secrets
Argo CD keeps repository credentials for OCI and Helm-over-OCI sources as Kubernetes Secrets, so anyone who can read those Secrets in the Argo CD namespace can read the registry token. Since Argo CD 3.0, repositories must be defined as Secrets rather than in argocd-cm, which makes Secret access the main boundary to review. Use read-only pull accounts scoped to the repositories each Application needs, restrict RBAC on Secrets in the Argo CD namespace, and confirm that rotation is part of your runbook.
Repo-server rendering artifact content
The repo-server runs Helm and Kustomize on the content it pulls, so a chart from a registry is executed code in the rendering path, not inert data. Helm templates can reach values and files the chart author chose to read, and a crafted chart can try to read out-of-tree paths. Treat the repo-server as a trust boundary, pull only from registries and projects you have vetted, and review rendered output for a new chart version before enabling automated sync.
Who can push to the source project
Argo CD syncs whatever the tag or digest in the registry resolves to, so anyone with push rights to the source project can change what reaches production. A tag such as latest or a mutable release tag can be re-pointed without any change in Argo CD. Limit push rights to the build pipeline account, require pull-request or pipeline approval before publishing, and pin Applications to immutable tags or digests where your tooling supports it.
Untrusted publishers and provenance
A registry can host artifacts from teams or external sources whose build process you have not reviewed. Argo CD checks the artifact layer media type but does not establish who built it or whether it is the artifact you intended. Maintain an allowlist of publishing projects, verify signatures or provenance with the tooling your registry supports, and confirm the registry's own content trust settings before accepting third-party charts.
Credential redaction in logs and API responses
Argo CD redacts cluster, Git and OAuth2 credentials from API responses and logs, but that protection covers the project's own output, not everything your registry tooling or CI jobs print. Registry tokens can still leak through pipeline logs, shell history during setup, or manifests that embed them. Check that ORAS and CI steps mask tokens, avoid passing credentials as command-line arguments, and test that a sample token does not appear in Argo CD logs after a sync.
Questions teams ask before deploying from OCI with Argo CD
What does deploying from an OCI registry with Argo CD cost?
The cost is mostly the time of the people doing the work, plus the registry and cluster capacity you already run or add. Argo CD itself is licensed under Apache-2.0 and the project offers no paid edition, so there is no license fee for the controller. The main cost components are the design of your artifact layout and credentials, the repo-server and registry configuration, the pipeline that pushes artifacts, and the verification and handover. Ask any partner for a quote built from a written scope that names each of these items, and separate one-time setup from recurring upgrades and support.
Which parts of the work drive the effort up?
Effort rises with the number of source types and repositories, the number of teams publishing artifacts, and how much your current pipeline differs from the OCI pattern. The items that most often add time are:
- Custom layer media types that must be allowed on the repo-server with ARGOCD_REPO_SERVER_OCI_LAYER_MEDIA_TYPES
- Multi-layer artifacts, which Argo CD does not accept under the single-layer rule
- Path rules for OCI Helm charts, where the path must be '.'
- Separate credential handling for Helm charts reached over OCI and for plain OCI repositories
If you already use Git and have a stable registry, the work is smaller.
How long does a first OCI source take to set up?
Duration depends on how many sources you connect, whether a registry already exists, and how mature your artifact publishing pipeline is. A first source usually takes longer than later ones because the team must agree on artifact naming, tagging, media types and credentials. Time also grows with access reviews, testing of a sync and rollback, and any registry hardening you require. Ask for a timeline in the written scope that lists each source, the registry work and the verification steps, rather than a single overall number.
What does our team need to provide for the engagement?
You will need to provide access to the Argo CD instance, the target clusters and the registry, plus named owners for each. Expect to supply the artifact layout you want, the credential policy, the identity groups that map to Argo CD roles, and the change process for pushing new artifacts. Your team also needs to confirm the registry's own behavior, such as how it handles tags and authentication, because the controller depends on it. Agree these inputs before work starts so the scope stays fixed.
Can our in-house platform team do this without a partner?
Yes, a team with Kubernetes and Argo CD experience can build an OCI source in-house, and the official OCI guide covers the core steps. The work is most manageable when one engineer owns the credential model, one owns the artifact push process, and someone reviews the repo-server settings for media types. Teams that lack registry or Argo CD upgrade experience often spend more time on edge cases such as custom media types and Helm path rules. Compare the internal effort against a fixed-scope partner quote, and confirm the skills gap before committing.
How does an OCI source compare with a Git source?
A Git source stores manifests in a repository and gives you a commit history and pull request review by default. An OCI source stores packaged manifests or charts in a registry, which suits teams that already publish versioned artifacts and want immutable tags. Git remains simpler for many small teams, while OCI adds a registry dependency, extra credential types and the single-layer rule to manage. Choose OCI when the artifact model fits your release process, and confirm the registry's availability and access controls before you move workloads.
What security checks should we run on OCI sources?
Treat each registry as a source of deployable content and control who can publish to it. Argo CD authenticates API requests with JSON Web Tokens and redacts repository credentials from responses and logs, but the repo-server runs Helm and Kustomize on repository content, so an untrusted artifact is a real risk. Limit publish rights, restrict which media types you allow, and review the credential scope for each repository. Confirm with your security team how the registry scans artifacts before they reach a cluster.
Limits to confirm in your environment
OCI sources add moving parts that Git does not have: the registry, its version and replication, the artifact types Argo CD will accept, and the network path into your clusters. Each card below is a question to put to the vendor or to answer on a test cluster before you commit a production delivery path to an OCI registry.
Does the registry serve OCI Helm charts
Ask whether the registry you plan to use serves Helm charts as OCI artifacts and whether Argo CD can pull them through the same credential path you will use in production. Harbor is one example: its 2.8 release post states that from v2.8.0 it no longer includes ChartMuseum and serves OCI Helm charts instead. Confirm this on your chosen registry version, not from memory, and pull one chart from a test cluster before you write the Application manifests.
Which artifact types your Argo CD version accepts
Confirm the single-layer media types your Argo CD version accepts by default, then test any artifact your pipeline produces that uses a different type. Anything outside the default list will fail until the repo-server allowlist is changed. Record the Argo CD version you tested against, because the accepted types are part of what you are relying on when you upgrade.
Harbor version and upgrade behavior
If Harbor is the registry, ask which release line you are on and what the upgrade does to your data. Harbor v2.15.2 upgrades the bundled database from PostgreSQL 15 to PostgreSQL 18 on container startup and replaces Redis with Valkey, and its release notes recommend a backup first. Harbor v2.15.3 blocks webhooks to internal addresses by default. Test any upgrade in a staging registry before your clusters depend on the new version.
Replication topology and source of truth
If charts are replicated between registries, confirm which registry is the source of truth and which one Argo CD reads. Ask whether the replication rule runs push or pull, which filters select the chart, and whether it runs manually, on a schedule or on push events. A rule that copies an older tag than the one your Application expects produces a sync that looks correct but deploys a different chart version.
Air-gapped mirroring path
In an isolated network, ask how charts and images reach the registry that your clusters can reach. Confirm whether the mirror is a one-way transfer, how often it runs, and whether a proxy cache or replicated copy can serve the cluster when the upstream is unreachable. Verify the path with a chart pull from inside the isolated network, since a registry that is reachable only from outside will break every sync.
Effect of changing the media type allowlist
Ask what changing ARGOCD_REPO_SERVER_OCI_LAYER_MEDIA_TYPES does to the repo-server and to every Application that reads from the registry. Widening the allowlist lets more artifact types reach manifest generation, which widens what the repo-server processes. Test the change on a non-production cluster, confirm which artifacts become accepted, and review who is allowed to change repo-server settings.
Using Harbor as the OCI source behind Argo CD
Harbor is a good fit as the OCI source for Argo CD when you want the registry under your own control, because it stores container images and Helm charts as OCI artifacts in the same place. Harbor is licensed under Apache-2.0 and extends the open-source Distribution registry with projects that use role-based access control, LDAP, Active Directory and OIDC single sign-on, vulnerability scanning, garbage collection, audit logs and a REST API. Since v2.8.0 Harbor serves OCI Helm charts instead of ChartMuseum, so one registry can hold both the charts Argo CD renders and the images those charts reference. Argo CD itself does not require Harbor. Any OCI-compliant registry that accepts the layer media types in use will work, so the registry choice should follow your identity, retention and replication needs rather than the tool that reads from it.
Before you point Argo CD at Harbor, decide who pushes and who pulls. Give the Argo CD repo-server a read-only robot or service account scoped to the project that holds the charts, and keep push rights with your CI pipeline. Confirm that the repository credential type and path rules in the Argo CD configuration match the artifacts Harbor actually serves. If you use replication rules to copy artifacts between sites, check the filters and trigger type so that the cluster in the second site reads the same tags Argo CD expects. Harbor replication can run on a schedule, on push or retag events, or manually, and each choice changes how quickly a new chart version appears in another site. Confirm these settings in your own Harbor environment, because a replication rule that filters on the wrong tag pattern will look healthy while Argo CD fails to find the version it was told to deploy.
Plan Harbor upgrades as separate work from Argo CD upgrades. Harbor v2.15.2 changed the bundled internal database from PostgreSQL 15 to PostgreSQL 18 on container startup and replaced Redis with Valkey as the cache backend. Its release notes recommend a backup before upgrading and a reindexdb run if index problems appear. Harbor v2.15.3 blocked webhooks to internal network addresses by default and made signing unsigned images fail in projects that enforce content trust, so pipelines and integrations that depend on those behaviors need testing first. Take and verify a backup of the Harbor database and storage, test the upgrade in a non-production copy, and confirm that Argo CD can still pull charts and images afterward. Check the current Harbor releases before you schedule the change, because patch releases for older lines continue to appear.
How DeployOpen scopes and delivers OCI source setups
DeployOpen plans, implements and documents self-hosted open-source platforms inside your own infrastructure, including Argo CD source configuration for OCI registries. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Inventory which artifacts move to OCI and which stay in Git, with their media types and owners
- Confirm the registry product, its access model and whether the registry runs in your network
- Record the written scope, deliverables and timeline before any repository credential is created
How we build
- Create oci and Helm-over-OCI repository credentials as Kubernetes Secrets, with paths set to '.' for OCI charts
- Verify that each artifact has a single layer with an accepted media type, and document any extra types allowed on the repo-server
- Build a repeatable ORAS push step so manifests and chart packages follow the same tagging and review path
How we hand over
- Deliver runbooks covering credential rotation, tag conventions and how to add a new OCI source
- Document the repo-server settings, media type exceptions and the reasons each one exists
- Walk your platform and security teams through a test sync, a failed-pull case and the recovery steps
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover
- Review Argo CD minor releases and registry upgrade notes before your teams move to a new version
- Confirm current registry behavior with the vendor and your own environment before any change window
