Why Argo CD repository credentials need a plan before the second team onboards
When one or two repositories connect to Argo CD through a manually added secret, the setup feels manageable. The problem appears when hundreds of repositories across several teams each carry their own credential. At that scale, per-repository secrets become hard to audit, hard to rotate and easy to leave behind after a team or repository is retired. Since Argo CD 3.0, repositories must be defined as Kubernetes Secrets rather than in the argocd-cm ConfigMap, so every repository credential is now a Secret object you create, label, review and rotate. Before the second team onboards, decide how that inventory will be structured, not after it has grown by copy and paste.
Two credential roles need to be kept apart. The pull credential is a Secret labeled repository that lets Argo CD read manifests, charts or OCI artifacts. If you use the Source Hydrator, a separate Secret labeled repository-write gives it push access to write rendered output back to Git. Give the write credential its own scope, its own owner and its own review, because it can change what the cluster deploys. Confirm in your own environment which Git hosts, Helm repositories and OCI registries each team uses, and whether any team will run the Source Hydrator, since that determines how many write credentials you must govern.
Three decisions shape the rest of the work. The first is whether credential templates will cover shared URL prefixes so that repositories without their own credential fields inherit one. Argo CD applies the longest matching URL prefix, regardless of definition order, which makes the template layout something to test rather than assume. The second is whether GitHub App authentication will replace personal access tokens or SSH keys for GitHub-hosted repositories, which depends on your organization's GitHub plan and whether the app can be installed where your repositories live. The third is your rotation model: who rotates each credential, how often your policy requires it, and how a rotation reaches every Secret that depends on it without an outage. Settle these three before the second team starts, because retrofitting them after repositories are already wired by hand is considerably more work.
Which credential type fits each repository source
This table compares the four ways Argo CD can hold repository credentials and the Source Hydrator write path, with what each authenticates, when it fits, and what it makes harder to audit. Read each row against your Argo CD version, because the labels and selectors that match a credential to a repository are the details most likely to differ between releases.
| Credential type | What it authenticates and when it fits | What it makes harder to audit | Who must confirm the behavior |
|---|---|---|---|
| Repository Secret (single source) | Authenticates one Git, Helm or OCI repository by exact URL. Fits a small number of sources with their own deploy key, token or password. | Each repository carries its own secret, so rotation and ownership must be tracked per source across the cluster. | The platform team, against the declarative setup documentation for the installed Argo CD version. |
| Credential template (URL prefix) | Applies shared credentials to every repository without credential fields of its own whose URL starts with the template URL. Fits an organization with many repositories under one host or path. | The applied credential is inferred from URL matching, so a new repository can pick up a broad credential without a review. The longest matching prefix wins regardless of definition order. | The platform team, by testing a repository under the prefix and checking which template it resolves to. |
| GitHub App credential | Authenticates as a GitHub App installation instead of a personal token, for GitHub-hosted repositories. Fits organizations that want installation-scoped access and tokens that are not tied to one user. | Permissions are set in the GitHub App and the installation scope, so access review happens in two places. Confirm the supported App fields and the token refresh behavior in your version. | The GitHub administrator and the platform team, against the Argo CD declarative setup guide and the GitHub App settings. |
| Repository-write Secret (Source Hydrator) | Holds push access, labeled repository-write, separate from the pull secret labeled repository. Fits teams that use the Source Hydrator to commit rendered manifests back to Git. | Write access is a separate credential that can change Git history, so it needs its own owner, scope review and rotation record. Confirm the labels and branch rules against the Source Hydrator guide. | The security team and the Git hosting administrator, against the Source Hydrator guide for the version in use. |
How credential templates match by URL prefix
A credential template applies only to repositories that have no credential fields of their own and whose URL starts with the template URL. If several templates match, the longest matching prefix wins, regardless of the order in which the templates were defined. For an Argo CD installation, this means one template stored as a Kubernetes Secret with the label argocd.argoproj.io/secret-type set to repo-creds can cover every repository under an organization's prefix, such as an HTTPS GitHub or GitLab group URL, without a separate Secret per repository. A narrower template for a single sensitive repository, or a repository with its own credentials, takes precedence over the broad one, so you can add exceptions without reordering anything.
The same mechanism carries the main risk. A broad prefix, such as a host name or a top-level group, grants the template's credential to every repository that a team later creates or mirrors under that path, including ones nobody has reviewed. Because repo-server clones whatever Argo CD is told to read, an unreviewed repository under a covered prefix can also supply Helm charts or Kustomize inputs that run inside your environment. Before onboarding a whole organization, confirm which repositories currently exist under the prefix, decide whether the credential should be read-only, and narrow the template to the subgroup you actually intend to cover. Check the exact URL form Argo CD compares against, since a trailing slash or a different host alias can change which repositories match.
Test matching before you rely on it. Create one template per prefix in a non-production Argo CD instance, add one representative repository for each, and confirm in the Repositories view which credential Argo CD reports as used and that the repository syncs. Then add a deliberately similar repository that should not match, and confirm it does not pick up the template. Record the results alongside the template definitions so reviewers can see the intended scope. Ask your Git host administrator to confirm how repositories are created and transferred under each prefix, because the scope of a template is only as stable as the naming and permissions that govern that path.
Choosing SSH, HTTPS token or GitHub App authentication
An SSH key authenticates Argo CD to a repository with a private key held in a repository Secret. The Git host decides what that key can read, so Argo CD can only reach what the key's account or deploy key is allowed to access. Confirm the scope on the host before you rely on it.
- Storage: the private key sits in a Secret labeled
argocd.argoproj.io/secret-type: repository, with the repository URL and ansshPrivateKeyfield. - Grant: a read-only deploy key scoped to one repository is the narrowest option. A personal user key inherits every repository that person can read.
- Lifetime and ownership: record who generated the key, which team rotates it, and where the public half is registered, so a departing engineer does not leave access behind.
- Host verification: confirm how host keys are verified and pinned in your Argo CD configuration, because an unverified host can be impersonated.
Confirm with your Git host whether deploy keys can be read-only, whether one key can serve several repositories, and whether keys can expire on a schedule.
HTTPS authentication uses a username and a token or password stored in the repository Secret and sent over TLS. These credentials are easy to reuse across repositories, and they often outlive the person who created them, so their scope and expiry need deliberate settings.
- Storage:
usernameandpasswordfields sit in a repository Secret alongside theurlandtype: gitfields. - Grant: a fine-grained token limited to named repositories with read permission is far narrower than a classic personal token, which can reach everything its owner can.
- Lifetime and ownership: set an expiry and a named rotation owner for every token. Record the date the token was created so the next rotation is not missed.
- Credential templates: one token can serve many repositories under a shared URL prefix through a credential template. This reduces copies of the secret but widens the blast radius if the token leaks.
Confirm with your Git host whether tokens can expire, whether service accounts are permitted, and how token permissions map to read and write access.
A GitHub App authenticates with an App ID, an installation ID and a private key. Argo CD exchanges these for short-lived installation tokens, and the organization chooses which repositories each installation can see. Ownership sits with the organization rather than an individual, so the setup survives staff changes.
- Storage: the
githubAppID,githubAppInstallationIDandgithubAppPrivateKeyfields live in a repository Secret. The private key is the sensitive item and needs the same protection as an SSH key. - Grant: repository selection at install time and the smallest set of permissions the Git flow needs.
- Rate limits: the REST API allows 15,000 requests per hour for GitHub Enterprise Cloud apps and 5,000 per hour for personal access tokens. Count the API calls your fleet makes, including status and hydrator calls, and compare them with your plan's limit before you move many repositories onto one app.
- Plan: the GitHub pricing page lists Team at $4 and Enterprise at $21 per user per month, so confirm which tier includes the app rate you need.
Check the rotation schedule for the app private key and confirm that the installation's repository list matches the repositories covered by your credential templates.
Risks that grow with the number of repository secrets
Each repository secret you add widens what a single leaked or misconfigured credential can reach. The six risks below are the ones that tend to appear as repository counts climb, and each one has a control you can set before the list gets long.
Broad credential template reach
A credential template matches every repository whose URL starts with its URL prefix, so a broad prefix can hand one credential to repositories nobody intended it to serve. Repositories with no credential fields of their own pick up the template automatically. Use the most specific prefix you can, define one template per organization or team path, and review which repositories match each template before you add a new one.
Write access through the pull secret
The pull secret labeled repository is the one Argo CD uses to read manifests, and it should never carry push rights. Push access for the Source Hydrator belongs in a separate secret labeled repository-write. Keep the write secret scoped to the hydrator's target repositories, and confirm with a test that the pull credential cannot push.
Credentials that outlive their owners
Deploy keys and personal access tokens often belong to a person who leaves, and the secret keeps working after the account is gone. Record an owner and an expiry for every repository secret, prefer app-based or machine identities over personal tokens, and rotate on a schedule that does not depend on someone remembering.
Untrusted content in the repo-server
The security documentation warns that the repo-server runs Helm and Kustomize on repository content, so a repository you do not control can influence what runs there. Limit which repositories Argo CD can read, keep the credentials for untrusted sources out of the same project, and review the access your repo-server has to other files before you grant new repositories.
Git host limits on shared credentials
Git hosts meter API traffic per credential, so one token or app serving hundreds of repositories can hit its request ceiling during a busy reconciliation window. Ask your Git host for the current limits for your plan and credential type, spread repositories across GitHub App installations where that fits, and monitor repository-server errors that look like rate limiting.
Secrets committed to Git by mistake
A credential pasted into a manifest, Helm values file or repository secret definition can end up in Git history, where deleting the file does not remove the value. Scan commits for credential patterns before merge, keep repository secret manifests out of application repositories, and treat any exposed value as compromised and rotate it.
Setting up repository credentials and templates in order
This sequence moves a fleet of Git, Helm and OCI sources from ad hoc credentials to scoped templates that Argo CD can match by URL prefix, with a check after each step so that gaps surface before production syncs depend on them.
Inventory repositories by host and URL prefix
The platform team lists every Git, Helm and OCI source that Argo CD will read, grouped by host and by the URL prefix they share, such as one organization or one project path on a Git host. Record which sources already carry their own credentials, because those ignore templates entirely. Record which sources need push access, since only the Source Hydrator uses write credentials. The step is done when every application source maps to one row in the inventory and each row names an owner. Confirm the list against the Argo CD application manifests, not against memory, because forgotten sources are the usual cause of sync failures after a credential change.
Decide which prefixes need a template
Choose the URL prefixes that deserve a credential template. A template is worth creating where many repositories share one host and one access model, and a single-repository credential is better kept as a repository Secret. Remember that a template applies only to repositories without credential fields of their own, and that the longest matching prefix wins regardless of the order in which templates were defined. Write the prefix decisions in the inventory with the reason for each. The check is a short table in which every prefix has one template or one explicit exception, and no two prefixes overlap in a way that you would not be able to explain in review.
Create the narrowest Git access
For GitHub, the platform team creates a GitHub App for the organization and installs it only on the repositories the inventory lists, rather than using a personal access token tied to one engineer. Grant read-only repository permissions for pull credentials and add write permissions only where the Source Hydrator needs to push. Record the App ID, installation ID and the private key location in the secrets owner's register, and check which of these values your version of Argo CD expects by name. Other Git hosts and Helm or OCI registries need an equivalent read-only account or token. The check is a test API call with the new credential that succeeds for an included repository and fails for an excluded one.
Define the credential template Secret
Create a Kubernetes Secret in the Argo CD namespace that carries the template label Argo CD expects, sets the URL prefix, and holds the credential fields for that repository type. Confirm the exact label key, value and field names in the declarative setup documentation for the Argo CD version you run, because these have changed between releases and the upgrade notes call out some of the changes. Apply the Secret through your normal GitOps path, not with an imperative command that leaves no record. The check is that the Secret appears in the Argo CD UI or CLI as a repository credential template, with the prefix you intended, and no secret values are displayed.
Add repository Secrets only where a template cannot cover the source
For repositories that use different credentials or sit outside every template prefix, create a repository Secret with the label for repositories. Do not duplicate credentials that a template already supplies, because two sources of truth make rotation error-prone. Verify that the repository Secret has its own credential fields so it is not treated as a template match. The check is a list of exceptions in the inventory, each with a stated reason, and a count of repository Secrets that matches that list.
Add a repository-write Secret for Source Hydrator pushes only
The Source Hydrator pushes rendered manifests to a separate branch or repository, and it reads write credentials from a Secret carrying the repository-write label, distinct from the pull Secret for the same repository. Create this Secret only for the repositories that the Source Hydrator writes to, and limit the token or App permissions to those repositories. Keep it in the same namespace and under the same review process as the pull credentials so that its scope is visible. The check is that the Source Hydrator guide's expected behavior matches what you see in a test hydration run, and that a pull-only Secret for the same repository still cannot push.
Verify each repository with a test sync
For every repository in the inventory, confirm that Argo CD shows the repository as connected, then run a test sync of a non-production application that reads from it. Include at least one deliberately unmatched URL under a host that has a template, and confirm that Argo CD reports an authentication failure rather than silently using another credential. Record the result in the inventory. The step is done when every row shows a successful connection, every intended failure fails, and the test application reaches a healthy state. Repeat this check after any credential rotation.
Document rotation and revocation ownership
Assign an owner for each template and repository Secret, and write down how the credential is rotated, who approves the change and how the old credential is revoked after Argo CD has picked up the new one. Confirm rotation steps against the version-specific documentation before the first rotation, and rehearse one rotation on a test instance. The output is a short runbook linked from the inventory. The check is that the owner can rotate one credential from the runbook without consulting the original builder, and that the revocation step is recorded as complete.
Rotating repository secrets without breaking syncs
Rotate repository credentials by adding the new credential first, switching the Secret that Argo CD reads, confirming syncs succeed, and only then revoking the old value. Argo CD 3.0 moved repository definitions out of the argocd-cm ConfigMap and into Kubernetes Secrets, so a rotation runbook must target the labeled repository, repo-creds or repository-write Secrets directly. Any procedure that edits argocd-cm will change nothing for repositories that are now defined as Secrets, and a reviewer who finds that step in a runbook should treat the runbook as out of date.
For a personal access token or a password, the sequence is: create the replacement credential in the Git host with the same minimum scope, update the Secret's password or token field through your normal change path, then trigger a refresh on a representative Application that uses the repository and confirm it reaches Synced. For credential templates, one update to the template Secret covers every repository that inherits it, so the confirmation step should sample repositories from each URL prefix instead of one. Revoke the old token only after every sampled Application syncs and the Source Hydrator write path, if you use it, has pushed a commit using the repository-write Secret. Confirm with your Git host's documentation which token types can be revoked without affecting other integrations.
For GitHub App authentication, schedule rotation of the App's private key and of any installation tokens your tooling generates, and record the App ID, installation ID and key owner for each Secret. Generate a new private key in the App settings, add it alongside the old key in the Secret where your configuration supports it, verify syncs, and then delete the old key on GitHub. Keep ownership records in a register that names a team, a rotation date and the Secret's namespace and name. Secrets must never be committed to Git, including in base64 form or inside Helm values, because the repository is the one place every reader of the change history can see. Confirm with your secret manager or sealed secret tooling how the Secret is delivered to the cluster without being stored in plaintext in Git.
Limits to confirm in your environment before rollout
Several limits in a credential design depend on versions and plans that change outside this page. The items below are what we confirm during scoping, so the rollout is built on your actual Argo CD release, Git host and plan rather than on assumptions.
Argo CD minor version and patch support
Confirm which Argo CD minor version you run and whether it is one of the three most recent minor versions that still receive patch releases. Credential handling changed across major versions, so a version that has fallen out of patch support is a rollout risk in its own right. The current patch releases are published on the project's GitHub releases page, and we check your running version against that list during scoping. If you are on 2.x, the Argo CD 3.0 requirement below applies to your plan as well.
Repositories as Kubernetes Secrets
Argo CD 3.0 removed repository definitions from the argocd-cm ConfigMap, so every repository and credential template must be defined as a Kubernetes Secret. Teams that carried repository entries across an upgrade from 2.x often discover this only when syncs fail. We confirm which definitions still live in ConfigMaps, how the Secrets are labeled, and who can read them in the Argo CD namespace before any credentials move.
Git host plan and API rate limits
Confirm the plan your Git host is on, the number of API requests your Argo CD installation and webhooks consume per hour, and whether GitHub App or personal access token authentication is used. Rate limits differ by credential type, so the same repository count can behave differently under a GitHub App than under a token. We check these limits against the number of repositories, applications and polling intervals in your design before choosing an authentication model.
GitHub repository size and file limits
Confirm the repository size and file limits that apply to every repository Argo CD will read. GitHub recommends keeping the .git folder under 10 GB and single objects under 1 MB, and it enforces a 100 MB maximum file size and a 2 GB maximum push size. Large generated manifests, binaries or vendored charts that exceed these limits will fail to sync or push, so we check the repositories you plan to register for oversized content during scoping.
Self-hosted Git server support status
If your repositories live on GitHub Enterprise Server or another self-hosted Git server, confirm that the release you run is still supported by its vendor. GitHub Enterprise Server supports a limited set of recent feature releases, so an out-of-support instance can lose security fixes while Argo CD keeps working. We confirm the exact release, its end-of-support date and the TLS certificate chain Argo CD must trust before the credential rollout is scheduled.
Write credentials and hydrator scope
Confirm whether any repository needs push access for the Source Hydrator, since write credentials are stored in a separate secret labeled repository-write. Each write credential widens what a compromised Argo CD component can change, so we confirm which repositories need it and which service accounts own the token. Confirm this list with your Git host administrators before any write secret is created.
Questions teams ask before managing repository credentials
How much effort does a repository credential rollout take?
Effort depends on how many Git hosts, repositories and owners are involved, and on how the credentials are authenticated. A rollout that covers a few hosts and a single credential type is mostly declarative work: writing the credential templates and repository Secrets, testing pulls, and documenting the owners. Effort grows as the number of repositories grows, because each repository needs its URL matched by a template or its own Secret, and each owner needs to confirm access. GitHub App authentication adds setup on the Git host side, and rotation requirements add a recurring process on top of the one-time build. Ask any partner to break the quote down by these drivers so you can see what changes if the inventory grows.
Can our internal team manage repository credentials alone?
Often yes, if the team already runs Argo CD and has someone comfortable with Kubernetes Secrets, RBAC and the Git host's admin console. The Argo CD declarative setup approach is well documented, and credential templates by URL prefix reduce the number of Secrets to maintain. The harder parts are usually organizational rather than technical: getting an accurate inventory of repositories, agreeing who owns each credential, and building a rotation routine that people actually follow. If those gaps exist, a partner can help close them in a fixed-scope engagement and hand over a runbook your team can operate afterward.
What access and information do we need to provide?
Plan to provide three things before work starts:
- Administrative access to the Git host (for example, the organization settings where GitHub Apps are installed or tokens are issued)
- Kubernetes access to the Argo CD namespace and the ability to create Secrets there
- A list of repositories, including Git, Helm and OCI sources, with the team or person who owns each one
You should also confirm which Git hosts are self-hosted and which are cloud-hosted, since that changes the authentication options available to you. Any credentials you need to rotate should be identified in advance so the change can be scheduled.
How long does a credential rollout take in practice?
Duration is set by the size and state of the repository inventory, the number of Git hosts, and how many owners must approve changes. Teams with clean inventories and existing Argo CD access often finish faster than teams that discover unowned repositories during the work. Other factors include whether GitHub Apps need to be created and installed, how many environments need to be tested, and whether rotation is built into the same engagement. Ask for a timeline that lists the milestones and the dependencies on your owners, not a single number detached from the scope.
What does a fixed-scope quote cover?
A fixed-scope quote covers the work described in a written scope: the repositories and Git hosts in scope, the credential types (Git, Helm and OCI), the authentication method for each host, the credential template and Secret layout, verification steps, the handover documentation, and any rotation procedure agreed for the engagement. It should also state what is excluded, such as repositories added later, changes to the Git host itself, or ongoing support. DeployOpen does not publish a price list, so the quote follows from that written scope. Ask for it to name each deliverable and the client responsibilities that must be met for the timeline to hold.
Do GitHub App credentials cost more to manage than tokens?
The Argo CD setup itself is similar in both cases: you create a Secret that Argo CD reads. The difference is in the Git host work and the ongoing process. A GitHub App is installed on the organization or selected repositories and authenticates with its own identity, which usually makes ownership and rotation clearer but requires an administrator to create and manage the app. Personal access tokens are quicker to start with, but they are tied to a person and require more manual rotation. Costs of the Git host plan itself are separate, and GitHub's pricing page lists per-user rates for its Team and Enterprise plans that you should check against your own setup.
How do write credentials for the Source Hydrator change the work?
The Source Hydrator needs push access, which is configured with a repository Secret labeled repository-write, separate from the read-only Secret labeled repository. That separation adds a second credential per hydrated repository and a second set of owners to confirm. Scope it carefully: write access should be limited to the repositories the hydrator actually pushes to, and the credential should be reviewed during every rotation. Plan the rollout so that pull and write secrets are documented together, since mismatches are a common cause of failed hydration.
How DeployOpen scopes and delivers Argo CD credential work
DeployOpen plans, implements, documents and supports self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For Managing Argo CD repository credentials and credential templates, we start from your repository inventory and agree the design in writing before any change is made to your clusters.
How we scope
- Inventory of Git, Helm and OCI sources, grouped by host and URL prefix
- Decision record on credential templates, GitHub App authentication and write credentials
- Written list of which Argo CD projects and teams may use each credential
- Named owner for credential rotation, revocation and access reviews
- Fixed-scope agreement with deliverables and timelines confirmed before work starts
How we build
- Repository Secrets and credential templates defined as declarative manifests in Git
- GitHub App installation configured with the minimum repository permissions needed
- Repository-write secrets separated from pull secrets for Source Hydrator use
- Test repositories and sync checks run in a non-production Argo CD instance first
- Review of repo-server exposure to untrusted repository content
How we hand over
- Runbook covering template precedence, secret layout and rotation steps
- Verification checklist confirming each repository authenticates through the intended credential
- Documented procedure for revoking a compromised token or app key
- Knowledge transfer sessions with the engineers who will operate the setup
- Written record of the decisions and trade-offs made during the build
How we support
- Optional retainer for upgrades across Argo CD minor releases and patch releases
- Periodic review of credential scope as repositories and teams change
- Re-testing of credential flows after Argo CD or Git host changes
- Support for rotation events and access reviews on an agreed cadence
- Changes handled through a new written scope rather than open-ended work
