TLS Failed to Verify Certificate: Connecting to ACR Registry using Private Endpoint ADO Pipeline

Resolve the "TLS Failed to Verify Certificate" error in Azure DevOps pipelines when connecting to an Azure Container Registry (ACR) via a Private Endpoint by ensuring the pipeline agent can resolve internal DNS names and trusts the correct root certificates. This issue typically stems from network isolation or missing certificate trust stores on the build agents.

Understanding the Network Isolation

When you configure an Azure Container Registry with a Private Endpoint, standard public internet routes are blocked for that registry. The registry becomes accessible only through your Virtual Network (VNet). In an Azure DevOps self-hosted agent scenario, this creates a complex networking topology. The agent must be able to reach the private IP address assigned to the ACR Private Endpoint. If the agent is running on a different subnet or outside the VNet without proper peering, it cannot establish the TCP connection required for TLS handshake. Even if the network path exists, the TLS verification failure indicates that the client (the agent) does not recognize the certificate presented by the ACR. ACR uses managed identity and automatically provisions SSL/TLS certificates. These certificates are signed by Microsoft’s internal certificate authorities. For a secure connection to succeed, the machine running the Azure DevOps agent must have these specific CA certificates in its trusted store. Without them, the operating system rejects the connection as untrusted, resulting in the generic TLS error message.

Verifying DNS Resolution

Before diving into certificates, confirm that the agent can resolve the ACR domain name to the private IP. Public DNS servers will return the public IP or fail entirely because the Private Endpoint disables public access. You need to ensure that the agent is using the VNet’s internal DNS server. On Linux agents, check the /etc/resolv.conf file. On Windows agents, verify the network adapter settings. If the agent relies on public DNS like Google's 8.8.8.8, it will never find the private endpoint. Use the following command to test resolution from the agent machine:

nslookup <your-registry-name>.azurecr.io

The response should show an IP address within your VNet’s CIDR range, not a public Azure IP. If it returns a public IP or times out, the DNS configuration is incorrect. Ensure that Azure DNS integration is enabled for your VNet or that you have configured conditional forwarders correctly. This step is critical because even with perfect certificates, a DNS mismatch prevents the initial connection attempt.

Configuring Trusted Root Certificates

The core of the "TLS Failed to Verify Certificate" error is often a missing trust anchor. Self-hosted agents do not always come pre-loaded with the latest Microsoft enterprise CA certificates, especially in minimal containerized environments. You must explicitly add the Azure infrastructure certificates to the agent’s trust store. For Linux-based agents, you can update the certificate store using the package manager. Run the following commands to install and update the CA certificates:

sudo apt-get update
sudo apt-get install ca-certificates
sudo update-ca-certificates

On Windows agents, you may need to manually import the relevant certificates into the "Trusted Root Certification Authorities" store. Microsoft provides documentation on which specific certificates are required for Azure services. Often, simply updating the OS and applying the latest security patches ensures that the necessary root CAs are present. However, in hardened or custom-built images, you might need to download the specific Microsoft IT TLS CA certificates and import them programmatically during the agent initialization phase.

Checking Agent Network Configuration

If DNS and certificates are correct, verify the agent’s network interface. Ensure that the agent is connected to the same VNet or a peered VNet that has a route to the ACR subnet. Use PowerShell or CLI tools to inspect the routing table. Look for a default route or a specific route pointing to the Private Endpoint’s gateway. If the agent is in a different subscription, ensure that VNet peering is bidirectional and that resource locks or NSG rules are not blocking traffic on port 443. You can also use curl or Invoke-WebRequest from the agent to test connectivity directly to the ACR URL. This isolates whether the issue is with the Azure DevOps task runner or the underlying network stack. If curl fails with the same TLS error, the problem is definitely at the OS or network level, not the pipeline configuration.

Pipeline and Task Adjustments

Sometimes the issue lies in how the Azure DevOps tasks interact with the environment. Ensure that you are using the latest version of the Docker@2 task or the AzureContainerRegistry@1 task. Older versions may have hardcoded behaviors that conflict with modern Private Endpoint implementations. Clear the cache and restart the agent service to force a fresh load of the certificate store and network configurations. Additionally, check for any proxy settings defined in the agent’s environment variables. If a proxy is configured, it might be intercepting the TLS connection and presenting its own certificate, which is not trusted by the ACR. Disable proxies for internal Azure resources if possible, or ensure the proxy is configured to pass through the ACR domain without inspection.

Frequently Asked Questions

Why does this work locally but fail in the pipeline?

Local machines often have updated certificate stores and direct VNet access via VPN or ExpressRoute. Pipeline agents run in isolated containers or VMs that may lack the specific Azure CA certificates or have restricted DNS resolution. Always replicate the exact network environment of the agent locally to debug these discrepancies.

Can I disable TLS verification to fix this quickly?

Disabling TLS verification is a severe security risk and not recommended for production pipelines. It exposes your registry to man-in-the-middle attacks. Instead, focus on installing the correct root certificates or fixing the DNS configuration to establish a genuine secure connection.

What if my agent is in a different subscription?

VNet peering must be established between the subscriptions hosting the agent and the ACR. Ensure that the peering is active and that network security groups allow traffic between the subnets. Cross-subscription communication requires explicit permission and correct routing tables to function properly.

How do I update certificates on a Windows agent?

Use the Microsoft Management Console (MMC) to open the Certificate Manager snap-in. Navigate to Trusted Root Certification Authorities and import the required Microsoft IT TLS CA certificates. Alternatively, use Group Policy or scripts to automate this process across multiple agents in your pool.

Does Azure DevOps Managed Identity help with this error?

Managed Identity solves authentication issues, not network or TLS verification errors. Even with Managed Identity, the underlying transport layer must successfully complete the TLS handshake. Therefore, resolving the certificate trust and DNS issues remains essential regardless of the authentication method used.