The Simplest Way to Make ArgoCD Mercurial Work Like It Should

Picture this: your team wants GitOps speed, but your source lives in a Mercurial repo that ArgoCD barely admits exists. You push, sync, and pray nothing breaks before the next deploy. It does not have to be that fragile. A clean ArgoCD Mercurial integration can be calm, predictable, and fast.

ArgoCD runs as the GitOps engine, constantly reconciling manifests from source control to Kubernetes. Mercurial (hg) is still the version control backbone in many organizations, prized for its clean branching model and strong immutable history. The puzzle is wiring them together so ArgoCD can track Mercurial changes just as it does with Git. Once that loop is tight, you get reproducible deployments without migrating every repo on day one.

At its core, ArgoCD talks to repositories over standard protocols like SSH or HTTPS. When Mercurial repositories expose those endpoints, ArgoCD simply polls the repo for new commits and re-applies desired state. The challenge is authentication and repo indexing. Setting up deploy keys or tokens for a Mercurial API can differ from the Git workflows most people know. Map the service account behind ArgoCD to a Mercurial user with read-only permissions. You can manage those credentials through a secret store and rotate them regularly, similar to how you’d handle GitHub deploy keys. This keeps your automation airtight without granting unnecessary rights.

Common best practices:

• Use SSH keys tied to short-lived credentials, ideally through an OIDC identity provider like Okta or Azure AD.
• Mirror critical Mercurial branches to a read-only replica if your main server has strict access controls.
• Align branch naming across repos so ArgoCD’s path and revision filters remain easy to read.
• Rotate repository credentials automatically using your CI pipeline to avoid human-managed tokens.
• Audit ArgoCD’s repo connections under SOC 2 or ISO 27001 guidelines to maintain compliance posture.

Teams that follow these steps see clear wins:

• Faster sync times and fewer failed deploys.
• Consistent commit-to-prod traceability across both Git and Mercurial sources.
• Easier onboarding, since engineers do not need to juggle multiple command-line tools.
• Stronger secrets hygiene through automated RBAC and expiration.
• Clearer logs and alerts that map commits directly to deployments.

Once this foundation is solid, developer velocity improves. You no longer spend hours debugging access errors or waiting for infra approvals. ArgoCD simply does what it does best: deploy what’s in source control, every time. And when those access rules need to scale across teams or clusters, platforms like hoop.dev turn those rules into guardrails that enforce policy automatically. No more drifting configs or endless key rotations.

If your team explores AI-based assistants or deployment copilots, a properly authenticated ArgoCD-Mercurial link gives them safe, scoped access. AI can track change intent without ever holding secrets, closing the loop between commit suggestions and cluster state.

How do I connect ArgoCD to a Mercurial repository?
Use ArgoCD’s repository configuration to point to your Mercurial endpoint, supply SSH or HTTPS credentials, and grant read-only rights. ArgoCD will detect and synchronize changes just like it does for Git, only the transport and authentication differ.

The real secret is patience and small steps. Once the connection works, automation handles the rest and your deployments become boring in the best possible way.

See an Environment Agnostic Identity-Aware Proxy in action with hoop.dev. Deploy it, connect your identity provider, and watch it protect your endpoints everywhere—live in minutes.