Declarative cluster and repository secrets in Argo CD

Register clusters and Git repositories in Argo CD as labeled Kubernetes Secrets, scope them to projects, and keep the credential values out of plain Git.

On this page

Declarative Argo CD cluster and repository secrets for multi-team GitOps

A platform team that registers clusters and repositories by hand with argocd cluster add and ad hoc repository commands usually cannot answer a simple audit question: which repositories can each team deploy from, and to which clusters. Argo CD reads cluster and repository definitions from Kubernetes Secrets that carry specific labels, so those definitions can be reviewed in Git, reproduced after a rebuild and checked by the same process as application changes. The Secret label `argocd.argoproj.io/secret-type` tells the controller whether a Secret describes a repository, a repository credential template, or a cluster.

This matters most when you run many clusters, many repositories or frequent rebuilds of the Argo CD installation. It also matters for audit evidence, because a declarative definition shows who approved a registration and when it changed. Argo CD 3.0 removed repository configuration from the argocd-cm ConfigMap, so any repository you rely on must be defined as a Secret in the Argo CD namespace. If your installation predates 3.0, plan that migration before you upgrade, and confirm the steps in the Argo CD 2.14 to 3.0 upgrade notes.

Argo CD is released under the Apache License 2.0, so the source and its declarative configuration model are available without a paid edition from the project. That licence says nothing about who supports your installation, how quickly fixes arrive or what you can expect from upgrades. Check the minor release cadence and patch window against your own change calendar, and confirm with your provider who handles security fixes for the version you run.

Which Secret type to use for clusters, repositories and credential templates

A cluster Secret registers one destination cluster with Argo CD. It lives in the Argo CD namespace and carries the cluster API server address, a name, and the credentials Argo CD uses to reach that cluster. Argo CD recognizes it through the label argocd.argoproj.io/secret-type: cluster. Use this type when a single cluster needs its own registration, which is the normal case for each production, staging or tenant cluster that Argo CD deploys to. The Secret is the declarative counterpart of running argocd cluster add, so the registration can be reviewed and versioned in Git like any other manifest.

  • What it holds: the server URL, a display name, and a config block with the authentication details for that cluster.
  • When it fits: one Secret per destination cluster, including clusters reached through an external auth provider.
  • Scoping: set the project field to bind the cluster to one AppProject, which restricts that project's applications to the cluster.
  • Review: treat changes to the server URL or credentials as high-impact changes that need the same approval as application changes.
  • Ask your team: which identity the Secret authenticates as on each destination cluster, and how that access is limited.

Before you commit any cluster Secret, confirm which fields your Argo CD version expects and how the credentials are supplied.

Configuration options and when each fits

This table compares the labels and fields that decide what a repository or cluster Secret does in Argo CD. Read each row as a question: which setting fits the registration you are making, and what breaks if that setting is wrong. Confirm exact keys and label values against the Argo CD version you run before you write manifests.

OptionWhen it fitsWhat breaks if it is wrong
Label argocd.argoproj.io/secret-type: repositoryOne repository with its own URL and credentials, such as a single private app repoArgo CD ignores the Secret as a repository, so applications that reference it fail to sync with an access error
Label argocd.argoproj.io/secret-type: repo-credsA credential template shared by every repository under one URL prefix, such as a Git organizationA more specific repository Secret or a longer matching prefix takes precedence, so credentials apply to the wrong repositories
Label argocd.argoproj.io/secret-type: clusterA registered destination cluster with a server URL, name and config blockThe cluster is not recognized as a destination, and applications targeting it stay unable to deploy
Field url on a repository or templateExact repository URL for a single repo, or a shared prefix for a credential templateA prefix that is too short or too broad grants credentials to unintended repositories
Field name on a cluster SecretA stable, human-readable destination name that application specs referenceRenaming the Secret or changing the name breaks every application that points at it
Field project on a repository or cluster SecretLimiting a repository or cluster to one AppProject so only that team's applications can use itLeaving it unset makes the entry available across projects, so another team can reach it if their project allows it
permitOnlyProjectScopedClusters on an AppProjectA shared platform where a team's applications must deploy only to clusters scoped to that teamIf left false, applications in the project can target clusters that are not explicitly scoped to it

Setting up declarative cluster and repository Secrets

This sequence moves Argo CD cluster registrations and repository credentials out of imperative commands and into labeled Kubernetes Secrets that your team can review, version and reapply. Each step ends with a check so you know the Argo CD settings took effect before you add the next layer.

  1. Prepare the Argo CD namespace and access

    The platform engineer confirms that Argo CD is running in its namespace, that the admin user is limited to initial setup or disabled, and that the person applying Secrets has permission to create them in that namespace. Use a Git-managed manifest directory for these Secrets so every later change is reviewed. Check that you can list the existing Secrets in the Argo CD namespace with kubectl and that the Argo CD server responds in the UI or CLI.

  2. Create a credential-free test repository

    Before any real credentials exist, add a public or read-only test repository as a declarative Secret with the repository label and no password. This confirms that the Secret label, namespace and Argo CD repo-server connection work without exposing a token. Check that the repository appears under Settings and shows a successful connection in the UI or with the CLI repository list command.

  3. Define a repo-creds template for the organization

    Create one Secret labeled argocd.argoproj.io/secret-type: repo-creds with a url field set to your organization's Git prefix, such as an https path that all team repositories share. Argo CD applies this credential to every repository whose URL starts with that prefix, and when more than one template matches, the longest match wins. Check that a repository under the prefix connects without its own Secret, which confirms the template is being read.

  4. Add single repository Secrets for exceptions

    For repositories outside the shared prefix, or ones that need a different deploy key or token, create a Secret with the repository secret-type label and the repo URL. Give it a distinct name, store only a reference to the credential, and avoid duplicating the template's values. Check that the exception repository connects and that the Secret appears when you filter the namespace by the repository label.

  5. Register each cluster as a labeled Secret

    For each destination cluster, create a Secret with the cluster secret-type label, a name and server URL, and the credential configuration your access model requires. Use a cluster identity that matches the least-privilege design your team has chosen for that cluster. Check that the cluster appears in the Argo CD cluster list with the expected server URL and a successful connection status.

  6. Attach project fields to scoped entries

    Set the project field on repository and cluster Secrets that belong to a single AppProject, so only that team's applications can use them. Enable permitOnlyProjectScopedClusters on the project when its applications should reach only its own clusters. Check that an application in another project cannot select the scoped repository or cluster, and that the project's own application still syncs.

  7. Sync the Secrets from Git and verify

    Commit the Secret manifests to the platform repository, excluding plain-text credentials, and let your delivery tooling apply them. Keep the actual secret values in an encrypted store or an operator that writes them to the cluster, as your secrets policy requires. Check the result by listing Secrets with the Argo CD secret-type labels, confirming each repository and cluster connects, and confirming that no credential values appear in the Argo CD UI or API responses.

Keeping credential values out of plain Git

The central tension in this section is that the Secret manifests describe who can deploy where, which is the configuration you want reviewed in Git, but they also carry tokens, private keys and passwords, which you do not want readable by everyone with repository access. Decide first which part of the file is configuration and which part is a credential value, because the answer determines where each piece can safely live. Cluster names, server URLs, repository URLs, project labels and the argocd.argoproj.io/secret-type label are reviewable metadata. The bearerToken, tlsClientKey, password and sshPrivateKey fields are the values that must not be readable in plain text.

There are four common ways to resolve this, and each fits a different team. Encrypting Secrets before they are committed, for example with a tool that encrypts only the data fields, keeps everything in one Git flow and suits small platform teams that accept a key-management responsibility. External secret operators keep the values in a dedicated secrets store and place only references in Git, which suits organizations that already run a central vault and want rotation handled there. Sealed or encrypted manifests work well when the cluster itself holds the decryption key. A dedicated repository for platform configuration, with narrow write and read access, is the simplest option when the number of people who can see credentials must stay very small. Confirm with each tool's own documentation how it handles key rotation, recovery and whether Argo CD can read the result, since this page does not assume the behavior of any specific product.

For the operator details, including the recommended operators on the destination cluster and the risks of plugin-based injection, read the Argo CD secrets management group rather than choosing from this summary alone. Whichever approach you pick, check that no decrypted value ends up in a rendered manifest, in an Argo CD application diff or in a backup you have not classified. Declarative setup describes the Secret fields that Argo CD reads, which is the reference to hold your chosen tool's output against.

Security risks in Argo CD cluster and repository credentials

Repository and cluster Secrets give Argo CD the reach to read code and write to clusters, so each one widens what an attacker can reach if it is misused. The cards below cover the places where that reach is easiest to underestimate: untrusted repositories, credential exposure in output, admin access, project scope, Secret access and traffic between components.

Untrusted repositories reach the repo-server

The repo-server runs Helm and Kustomize against repository content, so any repository a credential template or repository Secret points at can influence what that process executes and reads. Before you add a repository URL to a credential template, confirm who controls its contents and whether Kustomize or Helm features that read files outside the repository are enabled. Treat a repo-creds entry with a broad URL prefix as granting trust to every repository under that prefix.

Credentials are redacted, not hidden

Argo CD redacts cluster, Git and OAuth2 credentials from API responses and logs, which protects routine views of the UI and CLI. It does not change what the Secret object itself contains. Anyone who can read the Secret in the Argo CD namespace still sees the token, key or password in plain form, so redaction should be treated as a guard against accidental disclosure only.

Secret read access in the namespace

Repository and cluster credentials are ordinary Kubernetes Secrets labeled for Argo CD, so the RBAC that governs them in the Argo CD namespace decides who can read them. Grant get, list and watch on Secrets only to the platform identities that need them, and audit any role that matches on all Secrets. Check this with a kubectl auth can-i review for each team account, since a broad cluster role elsewhere can grant the same access.

Admin user left enabled

The built-in admin account is intended for initial setup. Once SSO or local users are configured, the user management guidance is to disable it by setting admin.enabled to false in the argocd-cm ConfigMap. An enabled admin account with a known or weak password gives a direct path to every credential and cluster that Argo CD manages, so confirm it is disabled and that SSO access works before you remove the fallback.

Broad project scope widens cluster access

A project's source and destination lists decide which repositories and clusters its Secrets can serve. A project that permits any repository or any destination lets a team deploy through credentials meant for other teams. Set the project field on each repository and cluster Secret, and enable permitOnlyProjectScopedClusters so project applications stay on the clusters assigned to them. Review these lists whenever a new cluster is registered.

TLS between Argo CD components

Argo CD uses TLS for traffic between its own components, and it authenticates API requests with JSON Web Tokens. Those protections cover the paths inside the Argo CD installation, but they do not cover the link from Argo CD to Git hosts or to clusters outside it. Confirm the certificate chain for each external repository and cluster endpoint, and decide where certificate data lives so that a trusted endpoint cannot be silently replaced.

Questions teams ask before changing how Argo CD gets its credentials

How much effort does moving from argocd cluster add to declarative secrets take?

The effort scales with how many clusters, repositories and credential types you have, and with how many places those credentials are referenced today. Each cluster registration and repository needs a labeled Kubernetes Secret written, reviewed and applied, and any existing entries created by the CLI need to be mapped to those Secrets without breaking current applications. Teams with a handful of clusters and one or two repositories usually have a small, contained change. Estimates grow when credentials are shared across projects, when they come from several Git hosts, or when the team has not yet chosen how the Secret values themselves will be stored. Ask any partner to break the quote down by cluster count, repository count and secret tooling decision before you agree on scope.

What do we need to provide before work starts?

You need read and write access to the Git repository that will hold the cluster and repository definitions, cluster-admin or equivalent rights on the Argo CD management cluster for applying Secrets, and a named owner for each credential who can approve scope and rotation. For each managed cluster, someone with access must confirm the identity Argo CD uses, the namespaces it may deploy into and the Git repositories each team is allowed to use. Access to the registries and Git hosts is needed to confirm which credentials are read-only, which can write, and which are deploy keys or tokens. Agree on where secret values will live before the first Secret is written, because that decision affects the Git layout.

Can our own team make this change without a partner?

Yes, a team that already runs Argo CD and Kubernetes can make this change internally, provided it has someone who understands Argo CD's Secret types and project scoping. The work is mostly careful authoring of Secrets, a staged rollout that keeps existing applications syncing, and verification that each project can reach only its intended repositories and clusters. Teams often choose a partner when the change touches many clusters at once, when credentials span several identity systems, or when the internal team has no time to review the result. A partner's written scope should state which parts are advisory, which are hands-on and what the client team must still do after handover.

What recurring work does a declarative secrets setup create?

Once credentials are declared in Git, recurring work includes rotating credentials on a schedule your security policy sets, reviewing changes to Secret definitions through the same pull request process as application code, and checking that what is in the cluster still matches what Git describes. Drift checks matter because someone can still run a CLI command or edit a Secret by hand. Access reviews for who can change registration Secrets, and periodic confirmation that repository credential templates still cover the right URLs, are also ongoing tasks. Ask any provider which of these they will run, which your team will own, and how often each review is expected to happen.

How do we rotate a repository or cluster credential without downtime?

Rotate by adding the new credential alongside the old one, confirming that a test application syncs with it, and only then removing the old value. For repository credentials, a credential template matching the repository URL can be updated in place while the new value is verified, so existing applications keep syncing. For cluster registrations, create the new identity on the target cluster first, update the labeled Secret, then confirm sync status on a non-critical application before revoking the old identity. Keep the change in Git so the rotation is reviewable and reversible. Plan a window for the rollback path and make sure the owner of each credential is available during the change.

How does DeployOpen quote this work?

DeployOpen scopes fixed work in writing before it starts. The written scope lists the clusters, repositories and credential types covered, the deliverables, the client responsibilities and the timeline agreed for each. DeployOpen does not publish a price list, so a quote follows from that scope. When you request one, ask for the scope to name the clusters and repositories in each phase, the secret tooling decision, the verification steps, the handover of documentation and any retainer for later rotation or drift checks. Quotes that cannot name what is included are a signal to ask for a clearer scope before comparing numbers.

Will moving credentials into Git expose them to anyone who can read the repository?

It can, if the Secret values themselves are committed in plain text. Labeled Secrets describe where Argo CD should connect and which credential it should use, but the sensitive values should be stored encrypted or referenced from a secrets store, not written into a Git repository readable by many people. Argo CD's security documentation notes that it redacts cluster, Git and OAuth2 credentials from API responses and logs, which helps, but it does not replace a secrets management decision. Confirm your approach with your security team before the first commit, and check repository access controls as part of the design.

How DeployOpen scopes and supports Argo CD secret management

DeployOpen plans and implements declarative cluster and repository Secrets for Argo CD inside your own infrastructure, so registrations and repository credentials live in labeled Kubernetes Secrets under review. Engagements are fixed-scope, with the scope, deliverables and timelines agreed in writing before work starts.

How we scope

  • Inventory every cluster and repository Argo CD must reach, and which team owns each one
  • Map repository credential templates to Git hosts and URL prefixes used across the organization
  • Decide which Secrets carry a project field and which projects may use each cluster
  • Agree in writing where secret values come from and who may change them

How we build

  • Write labeled cluster and repo-creds Secret manifests with the argocd.argoproj.io/secret-type label
  • Test longest-prefix matching of credential templates against each repository URL
  • Restrict project-scoped entries and confirm permitOnlyProjectScopedClusters behaves as designed
  • Keep secret values out of plain Git using the encryption or external secret approach you choose

How we hand over

  • Deliver the Secret manifests, folder layout and a Git change workflow for them
  • Document how to add a cluster or repository without running argocd cluster add
  • Provide a test record showing each registration and credential resolves as intended
  • Run a handover session with the engineers who will maintain the Secrets

How we support

  • Offer ongoing support, upgrades and continuous testing as a retainer after handover
  • Review Secret changes when Argo CD versions change how repository configuration is read
  • Confirm with your team which secret tooling, Git host and identity provider you already run
  • Quote recurring support from the written scope, with no price list published

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.