How Argo CD reads from Azure Repos and deploys to your clusters
Argo CD reads manifests from Azure Repos by polling a Git repository URL with credentials it holds in the cluster, then applies the rendered desired state to the clusters you register. If your Azure DevOps organization keeps Kubernetes manifests, Helm charts or Kustomize overlays in Azure Repos, Argo CD can reconcile them without a pipeline pushing changes to the cluster. The repository credentials are stored as Kubernetes Secrets in the Argo CD namespace, not in a configuration map, because Argo CD 3.0 removed repository definitions from argocd-cm. The Argo CD controller and repo-server run inside your own infrastructure, alongside the target AKS or other clusters, so manifests and cluster state stay under your control. Webhooks and the Azure DevOps pull request generator are optional additions that shorten sync time or create preview applications; they do not replace the polling path.
Each repository connection needs a decision before the first sync. Choose the Azure DevOps credential type, such as a personal access token or an SSH key, and decide who owns it, since a token tied to one engineer stops working when that person leaves. Confirm the token scope is limited to reading the repository, and plan how the secret is rotated. Argo CD's repo-server runs Helm and Kustomize against repository content, so only repositories your team controls should be registered, and the Argo CD project should restrict which repositories and destination clusters each application may use. Confirm with Microsoft's current documentation which authentication methods your organization and data location support, because token and key storage follows its own geography rules.
What you need in place before connecting Azure Repos
Connecting Argo CD to Azure Repos touches four areas: the Argo CD version and how it stores repository definitions, the Azure DevOps access model, the network path from the cluster to Azure DevOps, and the target clusters that will receive the workloads. Settle each one before you create a single repository secret, because the choices made here decide how credentials are rotated and how the webhook and pull request pieces are built.
Argo CD version and repository model
Argo CD 3.0 removed repository configuration from the argocd-cm ConfigMap, so repositories must be defined as Kubernetes Secrets. If you are on 2.14 or earlier, plan the upgrade notes review before you add Azure Repos, not after. Confirm which minor version you will run and whether it still receives patch releases under the project's release cadence. Define every Azure Repos connection as a Secret from the start.
Azure DevOps organization and project access
Identify the Azure DevOps organization, project and repositories Argo CD will read, and the Entra ID or Azure DevOps group that owns them. Argo CD only needs read access to the manifest repositories, so keep write permissions with the team that merges changes. Ask who approves access grants and whether the organization enforces conditional access policies that could block a non-interactive credential.
Credential type decision
Choose how Argo CD authenticates to Azure Repos before building anything. Options include a personal access token, a service account tied to a non-person identity, or an SSH key, and each has different rotation, audit and offboarding behavior. Confirm with Microsoft which authentication methods are currently supported for your organization type, because these options change over time. Record the owner, expiry date and rotation procedure for whichever credential you choose.
Network path to dev.azure.com
The Argo CD repo-server must reach the Azure DevOps endpoints over HTTPS, and the webhook path requires inbound reachability from Azure DevOps to the Argo CD API server. Map egress rules from the cluster or its NAT gateway, any proxy in front of it, and any firewall that inspects traffic. In segmented networks, ask your network team to confirm the exact hostnames and whether a proxy changes certificate chains.
Target clusters and workload identity
List the AKS clusters or other Kubernetes targets Argo CD will deploy to, and confirm how Argo CD will authenticate to each one. Registering AKS clusters through workload identity avoids long-lived cluster secrets, but it needs the identity, federated credentials and cluster RBAC planned together. Decide which Argo CD project each cluster belongs to before registration, so that the Azure Repos source and the destination are bounded from the start.
Data location and token storage
Azure DevOps Services stores source code in the geography you choose for the organization, but stores personal access tokens and SSH keys in a US datacenter. Record this in your data residency review before any Argo CD credential is created. If your policy requires that credential material stays in a specific region, confirm the current position with Microsoft and decide whether that requirement can be met with Azure DevOps at all.
Configure the repository connection, webhook and pull request generator in sequence
This sequence connects Argo CD to an Azure Repos repository, confirms it can read the repository, protects the webhook endpoint, and then generates Applications from Azure DevOps pull requests. Each step ends with a check so the platform team knows the previous step works before the next one depends on it.
Create the repository secret with Azure DevOps credentials
The platform engineer who owns the Argo CD namespace creates a Kubernetes Secret that holds the Azure Repos URL and the credential Argo CD will use to clone it. Argo CD 3.0 and later read repository definitions from Secrets rather than from the argocd-cm ConfigMap, so this Secret is the only place the repository is declared. Choose the credential type your Azure DevOps administrators approve, and confirm with them which identity the token or key belongs to and what access it grants. Store the Secret with the label Argo CD expects for repositories, and keep the file out of Git. Done when the Secret exists in the Argo CD namespace and contains the repository URL and credential fields, with no plaintext copy in version control.
Confirm the repository syncs
Run the Argo CD CLI or check the UI to confirm that the repo-server can reach the Azure Repos URL and read the default branch. Run
argocd repo listand look for the repository with a successful connection status. If the status shows an authentication or TLS error, fix the Secret or the network path before continuing, because every later step depends on Argo CD reading the repository. Done whenargocd repo listshows the Azure Repos repository with a Successful status and a test Application pointing at it can reach a Synced state.Set webhook basic authentication on Argo CD
Set the webhook.azuredevops.username and webhook.azuredevops.password keys in the argocd-secret Secret, or in the configuration location your install uses, so that Argo CD requires basic authentication on requests from Azure DevOps. Use a generated password stored in your secret manager, not one typed into a shell history. Restart the API server if your install requires it to pick up the change. Done when an unauthenticated POST to the webhook endpoint is rejected and a request with the configured credentials is accepted by the endpoint.
Configure the Azure DevOps service hook
In the Azure DevOps project settings, a project administrator creates a service hook that sends repository push events to the Argo CD webhook URL. Enter the same username and password set in the previous step as the basic authentication credentials, and choose the repository and branch events the team needs. Confirm the hook URL resolves to your Argo CD API server over TLS. Done when Azure DevOps shows the service hook as enabled and its test delivery returns a success response from Argo CD.
Verify a test push triggers a refresh
Make a small commit to the tracked branch of the test repository and watch the Application in the Argo CD UI or run
argocd app geton it. The application should refresh shortly after the push instead of waiting for the default polling interval. If nothing happens, check the Azure DevOps service hook delivery history and the Argo CD API server logs for rejected requests. Done when the commit appears as the new revision of the Application without a manual refresh.Create the ApplicationSet with the Azure DevOps pull request generator
The platform engineer adds an ApplicationSet that uses the Azure DevOps pull request generator to find open pull requests in the target repository and create a preview Application for each one. Set the organization, project, repository and target branch fields to match Azure Repos, and reference the credential Secret created earlier. Keep the generated Applications inside an Argo CD project with restricted destinations so preview environments cannot deploy outside their allowed clusters. Confirm the Azure DevOps token has read access to pull requests before applying the resource. Done when the ApplicationSet status shows it has generated parameters and one preview Application appears for each open pull request.
Check the generated preview Application
Open one of the generated preview Applications and confirm that it points at the pull request's source branch, deploys to the intended namespace on the intended cluster, and syncs without errors. Close the pull request in Azure DevOps and confirm that Argo CD removes its Application when the ApplicationSet reconciles, so preview environments do not accumulate. Done when the preview Application appears on pull request open, syncs from the pull request branch, and is deleted after the pull request closes.
Why polling, webhooks and the pull request generator behave differently
Argo CD notices changes in Azure Repos in two ways, and they should not be treated as interchangeable. By default, Argo CD polls the repository on a periodic refresh, so a commit reaches the cluster after the next refresh cycle. A webhook from Azure DevOps shortens that loop by telling Argo CD that something changed, so it refreshes the affected Application sooner. The webhook is an optimization on top of polling, not a replacement for it. Confirm the refresh interval in your own Argo CD configuration before you promise anyone a deployment time, because the value depends on how your installation is set up. Plan the webhook endpoint as an inbound path that must be reachable from Azure DevOps and protected by the optional basic authentication described in the webhook guide, using the webhook.azuredevops.username and webhook.azuredevops.password keys in the argocd-secret Secret.
The credentials on both ends must match exactly. The service hook you create in Azure DevOps has to send the same username and password that Argo CD expects, and a mismatch produces rejected deliveries that look like silent failures from the pipeline side. Store the password in a secret store and rotate it through the same process you use for other integration credentials. Verify the path with a test delivery from the service hook and confirm in the Argo CD logs that the refresh was triggered, rather than assuming the hook works because the configuration saved.
The Pull Request generator is a different mechanism. An ApplicationSet with this generator queries Azure DevOps for open pull requests in a repository and creates one Application per open pull request, so reviewers can see a preview environment before merge. When the pull request closes, the generated Application is removed according to the ApplicationSet's sync policy. The token used for these queries needs read access to the repository and its pull requests, and nothing broader. Confirm the exact scopes for your organization's personal access token or service principal against the generator guide, and keep the token in a Kubernetes Secret on the Argo CD side. Expect the number of generated Applications to grow with open pull requests, and plan cluster capacity accordingly.
Mapping Azure DevOps identities, repos and pull requests to Argo CD objects
This table maps Azure DevOps organization, project, repository, branch and pull request details to the Argo CD objects that consume them, such as repository Secrets, Application sources, ApplicationSet generator parameters and webhook settings. Use it as a checklist when wiring Azure Repos into Argo CD, and confirm exact parameter names against the Pull Request generator guide before you apply anything.
| Azure DevOps item | Argo CD object and field | What to check |
|---|---|---|
| Organization and project | Repository URL in a repository Secret (url) | The clone URL must include the organization and project path exactly as Azure Repos shows it in the clone dialog. |
| Repository name | Repository URL path segment in the Application source (repoURL) | Use the repository name, not the project name. Mismatched case or spaces are a common cause of failed fetches. |
| Credentials | Repository Secret keys such as username and password | Store a scoped personal access token or other supported credential in a Secret, not in the Application manifest or argocd-cm. |
| Branch or revision | Application source targetRevision | Point at a branch, tag or commit explicitly. Changing this field changes what Argo CD deploys, so review it in Git. |
| Path in repository | Application source path | Confirm the folder holds manifests Argo CD should render. Paths outside the intended tree widen what the repo-server reads. |
| Pull request fields | ApplicationSet Pull Request generator parameters | Confirm the Azure DevOps-specific parameter names and required values in the generator guide before templating them into Applications. |
| Pull request source branch | Generator output mapped into the Application targetRevision template | Preview-environment Applications depend on this mapping, so test it on a non-production cluster first. |
| Webhook basic authentication | Argo CD settings webhook.azuredevops.username and webhook.azuredevops.password | Set both values, store the password in a Secret, and configure the same pair in the Azure DevOps service hook. |
| Webhook payload | Argo CD webhook handler receiving Azure DevOps push events | Verify that a test push triggers a refresh of the expected Application and that rejected requests are logged. |
Securing the Azure Repos credentials, webhook and cluster access
Argo CD with Azure DevOps Repos touches four trust points: the repository credential, the webhook that triggers syncs, the repo-server that executes repository content, and the admin access that controls all of it. The cards below cover what to lock down at each point and where the Azure DevOps data location facts change the decision.
Store the PAT in a repository Secret
Define the Azure Repos credential as a Kubernetes Secret labeled for repositories, not in the argocd-cm ConfigMap, since Argo CD 3.0 removed repository configuration there. Argo CD redacts repository credentials from API responses and logs, but the Secret itself is only as protected as your cluster's RBAC and encryption at rest. Confirm who can read Secrets in the argocd namespace and whether etcd encryption is enabled. Keep the token out of Git and out of ticket attachments.
Limit the token to read scope
Argo CD only needs to clone and fetch from Azure Repos, so the personal access token should carry read access to the code scope and nothing else. A token with write or administrative scope turns a compromised Argo CD into a way to push commits to your repositories. Confirm the scopes available in your Azure DevOps organization, set a short expiry, and record an owner who is responsible for renewal before the token lapses and syncs fail.
Weigh the US location of tokens
Azure DevOps keeps source code and work items in the geography you choose for the organization, but personal access tokens and SSH keys are stored in a US datacenter. If your data residency rules cover credentials as well as code, this is a decision to make before you choose PAT or SSH access. Ask your Azure DevOps account team how this applies to your tenant, and document the outcome in your risk register. The option to use a GitHub App or another credential type is not available in Azure DevOps, so confirm alternatives with your team.
Enforce TLS on the webhook path
Azure DevOps service hooks post to the Argo CD API server, so the webhook endpoint must be reachable over HTTPS with a certificate Azure DevOps trusts. Terminate TLS at your ingress, do not expose plain HTTP, and confirm that the certificate chain is complete. Keep the webhook endpoint limited to what Azure DevOps needs, since the webhook only triggers a refresh and does not replace authentication to the API.
Rotate the webhook basic auth password
Argo CD can require basic authentication on webhooks through webhook.azuredevops.username and webhook.azuredevops.password. Store these values in the Argo CD Secret, use a long random password, and make the same change in the Azure DevOps service hook. Rotate the password on a schedule you write down, and on any staff change, by updating both sides in one planned change. Test the service hook after each rotation, because a mismatch shows up as silent sync delays rather than a clear error.
Treat repo-server exposure as a risk
The repo-server runs Helm and Kustomize against repository content, so anyone who can push a malicious chart, a Kustomize plugin reference or an out-of-tree file path can influence what runs in the repo-server. Restrict which repositories Argo CD can read through AppProjects, avoid allowing arbitrary Helm repositories, and keep the repo-server network path limited to Git hosts and registries. Review branch protection on repositories that feed production applications.
Keep the admin account for setup only
The built-in admin user should be used only to bootstrap Argo CD. Once SSO or local users are configured and tested, set admin.enabled to false so that no shared password remains as a standing path into the cluster. Keep the initial credential recovery steps documented for break-glass use, and confirm that the cluster administrators who hold them are the same people covered by your access review. AKS clusters registered through workload identity should be checked the same way, so Argo CD does not keep broader cluster rights than the applications it deploys require.
Common Azure Repos connection failures and how to fix them
This table lists the failures teams most often hit when Argo CD reads from Azure Repos or receives Azure DevOps webhooks, with the likely cause and the fix for each. Read each row by matching the symptom you see, then checking the cause column before changing credentials or webhook settings.
| Symptom | Likely cause | Fix |
|---|---|---|
| Repository sync fails with authentication errors | The repository credential is expired, revoked, or lacks read scope on the Azure Repos Git repository, or the URL points at a different organization or project | Confirm the repository URL matches the Azure DevOps organization and project, then recreate the credential with read access and store it as a repository Secret, not in argocd-cm |
| Webhook returns unauthorized | The basic authentication username or password configured in Argo CD differs from the values set on the Azure DevOps service hook | Set webhook.azuredevops.username and webhook.azuredevops.password in argocd-secret to match the service hook exactly, then send a test event from Azure DevOps |
| Pull request generator produces no Applications | The generator's organization, project, repository or token is wrong, or the token cannot list pull requests, or no open pull requests match the filter | Check the generator settings against the target repository, confirm the token can read pull requests, and verify at least one open pull request matches the configured filters |
| Changes in Azure Repos are not picked up promptly | No webhook is configured, so Argo CD relies on periodic polling of the repository | Add a webhook from Azure DevOps to the Argo CD API endpoint with basic authentication, and keep polling as a fallback if the webhook is interrupted |
| Requests return HTTP 429 throttling | Many concurrent requests from Argo CD, pipelines or other integrations exceed the throughput limits in a sliding five-minute window, so Azure DevOps delays or blocks them | Reduce polling and generator frequency, stagger ApplicationSet refreshes, limit parallel pipelines that call the same organization, and review usage patterns against Microsoft's rate limit documentation |
| Webhook events arrive but Applications do not refresh | The webhook reaches Argo CD but the repository URL in the event does not match the URL registered in Argo CD, often because of differences in casing or trailing path segments | Compare the repository URL in the webhook payload with the repository URL stored in Argo CD and align them |
Questions buyers ask before hiring help for Azure Repos
Can our internal team set up Argo CD with Azure DevOps Repos on its own?
Yes, a team with Kubernetes and Azure DevOps experience can do it alone, and many do. The work is well defined: a repository credential, a webhook with basic authentication, an ApplicationSet pull request generator if you need it, and cluster registration for AKS. The risk is rarely the first working sync. It is the parts that are easy to skip under deadline pressure: repository credentials kept out of Git, RBAC scoped by project, admin access disabled after SSO is configured, and high availability planned before production load arrives. Ask whether your team has someone who has run Argo CD in production and who can own those decisions after go-live.
What drives the effort of an Argo CD and Azure Repos setup?
Effort follows the shape of your delivery model, not the Argo CD install itself. The main drivers are:
- The number of Azure Repos repositories Argo CD must read, and whether they are separate repos or a monorepo
- Pull request volume, which determines how much the pull request generator and webhook handling matter
- The number of AKS clusters and the number of environments per cluster
- The credential model: a personal access token, a service connection, or workload identity for cluster access
- Whether SSO, multi-tenant projects and an existing Azure DevOps organization structure need redesign
Each added repository, cluster or team boundary adds design and verification work. Ask any provider to break its quote down by these drivers.
What does the Azure DevOps Basic plan cost per user?
According to Microsoft's Azure DevOps Services pricing page, the Basic plan is free for the first 5 users and then costs $6 per user per month. Basic plus Test Plans is listed at $52 per user per month. Argo CD itself does not require an Azure DevOps seat, since it only needs read access to repositories through a credential. The seat cost matters for the people who push commits, review pull requests and manage the repositories. Confirm current prices on the pricing page before budgeting, because your organization may already hold licenses that change the calculation.
What do we need to provide for the engagement?
Plan to provide three kinds of access and contacts before work starts:
- An Azure DevOps organization administrator who can create or review a read-only credential for the repositories, and configure the webhook with basic authentication
- A cluster administrator for the AKS clusters, who can approve Argo CD's role bindings and the workload identity setup
- Network contacts who can confirm routing from the Argo CD cluster to Azure DevOps and to the Kubernetes API of each target cluster, including any egress rules or private endpoints
You should also name a security owner for the credential rotation process and a Git owner who approves repository structure changes.
How long does an Argo CD and Azure Repos implementation take?
Duration depends on scope, and no single figure fits all environments. A narrow scope, with one Argo CD instance, a few repositories, one AKS cluster and a single credential model, is much shorter than a scope that adds SSO, several projects, multiple clusters and pull request based preview environments. Ask for a timeline in the written scope that lists the repositories, clusters, identity integration and testing steps, along with the review points where you approve each stage. Fixed-scope engagements agree deliverables and timelines in writing before work starts, so the duration you receive should trace back to those items.
Is Argo CD itself free to use with Azure Repos?
Yes. Argo CD is part of the Argo project and is released under the Apache License 2.0, which is identified as Apache-2.0. The project does not offer a paid edition. Your costs are the infrastructure to run it, the Kubernetes clusters it deploys to, the Azure DevOps seats your staff use, and any services you pay for, such as Azure Monitor or the team time for setup and operations. If a vendor charges a license fee for Argo CD itself, ask what extra support or tooling that fee covers.
What goes wrong most often when connecting Argo CD to Azure Repos?
Most failures trace to credentials, webhooks or the cluster network. Credentials that expire or are tied to a departed user stop syncs without an obvious error. Webhook basic authentication that does not match the username and password in Argo CD leaves applications to refresh on a polling interval rather than on push. Pull request generators fail quietly when the token lacks read access to pull request metadata. Also check that Azure DevOps throughput limits are not hit by heavy pipeline activity, since requests above the documented throughput units can be delayed or blocked with HTTP 429 responses. Ask any partner how they will test each failure path before handover.
Pairing Argo CD with AKS clusters registered through workload identity
Argo CD registers each target AKS cluster as a separate cluster entry, and that registration is independent of the Azure Repos connection. The repository credential lets the repo-server read manifests from Git, while the cluster credential lets the application controller create and update resources on the cluster. Plan these as two trust paths, and review them together, because a weakness in either one can change what Argo CD is able to deploy. Confirm the exact registration steps for the Argo CD version you run and for the current AKS workload identity setup, since both products change between releases and the Argo CD documentation is the authoritative reference for cluster secrets.
Where the client's Azure setup supports it, workload identity is the preferred approach for cluster access because it avoids long-lived kubeconfig tokens stored in Argo CD. In that model, the identity Argo CD uses on Azure is federated to a Kubernetes service account, and the cluster authorizes that identity through Kubernetes RBAC or Azure RBAC for AKS. Decide which identity the application controller uses for each cluster, scope its permissions to the namespaces that team owns, and record that mapping in the Argo CD project definitions. Confirm with the client's Azure administrators whether the tenant, cluster and identity configuration permits this model before committing to it.
Review the Azure Repos credentials and the AKS cluster credentials in the same design session, because a single identity or group reused across both paths widens the blast radius. Ask who can change repository secrets, who can register clusters, and whether a commit to the repository can reach a privileged cluster without a second review. Confirm the repository access method and the cluster access method against current Argo CD and Azure documentation, and write down the owner of each credential, its rotation process and how revocation would be tested before go-live.
How DeployOpen scopes and delivers the Azure Repos integration
DeployOpen plans, builds, tests and documents the Argo CD connection to Azure Repos inside your own Kubernetes and Azure environment. We start from a written scope that names the repositories, clusters, identity model and webhook design, then hand over a working setup with the runbooks your team needs to operate it.
How we scope
- Inventory the Azure DevOps organization, repositories, branch policies and the teams that own each repository
- Agree the credential model for repository access, including how Argo CD reads Azure Repos and who rotates credentials
- Define which AKS clusters are in scope, how workload identity is assigned and which pull request generator use cases apply
How we build
- Configure repository access and webhook basic authentication, then test that Argo CD refreshes applications on push events
- Set up the Azure DevOps pull request generator for the agreed branches and confirm the generated Applications match the scoped design
- Test sync, health and rollback behavior on a non-production AKS cluster before any production cluster is connected
How we hand over
- Deliver the configuration as code in your repositories, with the secret handling and access model documented for your team
- Provide a verification checklist covering webhooks, credential expiry, pull request generator output and cluster registration
- Walk through the operating runbook with the engineers who will own Argo CD, including what to check when a sync stops
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts
- Ongoing support, upgrades and continuous testing are available as a retainer for Argo CD and its integrations
- Ask any quote to separate one-time build work from recurring support, and confirm which Azure DevOps fees your organization already pays
