matchHost with path does not work for Docker registry credentials

[qixiang]

How are you running Renovate?

Self-hosted Renovate CLI

Which platform you running Renovate on?

GitLab (.com or self-hosted)

Which version of Renovate are you using?

43.77.0

Please tell us more about your question or problem

Problem

When configuring hostRules with a path-based matchHost for Docker registries (e.g. quay.io/org/repo), the credentials are never applied. This means Renovate cannot access private Docker images when per-repo credentials are required.

Example configuration:

{
  "hostRules": [
    {
      "hostType": "docker",
      "matchHost": "quay.io/myorg/myrepo",
      "username": "my-robot-account",
      "password": "***"
    }
  ]
}

This results in:

• getDigest() returning null
• Digest updates silently not being detected
• Warning: Could not determine new digest for update (docker package ...)

Why this happens

The https://docs.renovatebot.com/getting-started/private-packages/#host-rules say path-based matchHost is supported:

If you want to apply credentials only for a nested path within a host then write matchHost as a base URL like https://registry.company.com/nested/path/.

And the matchHost https://docs.renovatebot.com/configuration-options/#matchhost say:

If the value starts with http(s) then it will only match against URLs which start with the full base URL.

This works for most datasources because their API URLs share the same path prefix as the matchHost. For example, npm registry URLs like https://registry.company.com/nested/path/package start with https://registry.company.com/nested/path/.

However, the Docker v2 protocol inserts /v2/ as a path prefix in some API URLs, some example:

• manifest request: https://quay.io/v2/myorg/myrepo/manifests/tag
• tags list: https://quay.io/v2/myorg/myrepo/tags/list

With the example, the matchHost (after massageHostUrl) is https://quay.io/myorg/myrepo.
matchesHost() uses startsWith(), so none of the above API URLs match:

"https://quay.io/v2/".startsWith("https://quay.io/myorg/myrepo") returns false.

Because no credentials are found, getAuthHeaders() requests an anonymous token from the registry. The anonymous token lacks pull permissions for private repositories, so the subsequent manifest requests fail with 401.

Use case

This matters for container registries (e.g., quay.io) where different repositories may belong to different organizations, each with their own robot account credentials. These repositories are used in a code repository and users need to configure separate credentials per repository, not a single credential for the entire registry.

Proposed fix

Add a fallback credential lookup in getAuthHeaders() (lib/modules/datasource/docker/common.ts). When the initial hostRules.find() with the API URL returns no credentials, retry with the repository path URL (${registryHost}/${dockerRepository}), which matches the user-configured matchHost:

let rule = hostRules.find({
  hostType: dockerDatasourceId,
  url: apiCheckUrl,
});

// If no credentials found with the API URL, try the repository path URL.
// This supports per-repo matchHost like "quay.io/org/repo" where the
// matchHost path doesn't match Docker v2 API URLs (e.g. /v2/...).
if (!rule.username && !rule.password && !rule.token) {
  const repoUrl = `${registryHost}/${dockerRepository}`;
  const repoRule = hostRules.find({
    hostType: dockerDatasourceId,
    url: repoUrl,
  });
  if (repoRule.username || repoRule.password || repoRule.token) {
    rule = { ...rule, ...repoRule };
  }
}

The fallback only triggers when the initial lookup returns no credentials.

I have a working implementation with tests in #41967 if the approach is accepted.

Logs (if relevant)

I removed or replaced log lines that irrelevant or related to private data.

Logs

DEBUG: File config
       "config": {
         "hostRules": [
           {
             "hostType": "docker",
             "matchHost": "https://quay.io/org1/repo",
             "password": "***********",
             "username": "bot1"
           },
           {
             "hostType": "docker",
             "matchHost": "https://quay.io/org2/repo",
             "password": "***********",
             "username": "bot2"
           }
         ]
       }
DEBUG: Setting global hostRules
DEBUG: Adding password authentication for https://quay.io/org1/repo (hostType=docker) to hostRules
DEBUG: Adding password authentication for https://quay.io/org2/repo (hostType=docker) to hostRules
DEBUG: Dependency quay.io/org1/repo has unsupported/unversioned value some-tag-2.0 (versioning=docker) (repository=myusername/reproducer, baseBranch=main)
DEBUG: getDigest(https://quay.io, org1/repo, some-tag-2.0) (repository=myusername/reproducer, baseBranch=main)
DEBUG: getManifestResponse(https://quay.io, org1/repo, sha256:4d657c3853d8c2d9005da4f33baa553cb442d58defe81d98ec5e0806a66c0f79, head) (repository=myusername/reproducer, baseBranch=main)
DEBUG: Using queue: host=quay.io, concurrency=16 (repository=myusername/reproducer, baseBranch=main)
DEBUG: http cache: saving https://quay.io/v2/auth?scope=repository%3Aorg1%2Frepo%3Apull&service=quay.io (etag=undefined, lastModified=undefined) (repository=myusername/reproducer, baseBranch=main)
DEBUG: HEAD https://quay.io/v2/org1/repo/manifests/sha256:4d657c3853d8c2d9005da4f33baa553cb442d58defe81d98ec5e0806a66c0f79 = (code=ERR_NON_2XX_3XX_RESPONSE, statusCode=401 retryCount=0, duration=238) (repository=myusername/reproducer, baseBranch=main)
DEBUG: Unauthorized docker lookup (repository=myusername/reproducer, baseBranch=main)
       "registryHost": "https://quay.io",
       "dockerRepository": "org1/repo"
DEBUG: Request failed with status code 401 (UNAUTHORIZED): HEAD https://quay.io/v2/org1/repo/manifests/sha256:4d657c3853d8c2d9005da4f33baa553cb442d58defe81d98ec5e0806a66c0f79 (repository=myusername/reproducer, baseBranch=main)
       "err": {
         "name": "HTTPError",
         "code": "ERR_NON_2XX_3XX_RESPONSE",
         "timings": {
           "start": 1773736802540,
           "socket": 1773736802540,
           "lookup": 1773736802540,
           "connect": 1773736802540,
           "secureConnect": 1773736802540,
           "upload": 1773736802540,
           "response": 1773736802778,
           "end": 1773736802778,
           "phases": {
             "wait": 0,
             "dns": 6,
             "tcp": 720,
             "tls": 222,
             "request": 0,
             "firstByte": 238,
             "download": 0,
             "total": 238
           }
         },
         "options": {
           "headers": {
             "user-agent": "Renovate/0.0.0-semantic-release (https://github.com/renovatebot/renovate)",
             "authorization": "***********",
             "accept": "application/vnd.docker.distribution.manifest.list.v2+json, application/vnd.docker.distribution.manifest.v2+json, application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json",
             "accept-encoding": "gzip, deflate, br, zstd"
           },
           "url": "https://quay.io/v2/org1/repo/manifests/sha256:4d657c3853d8c2d9005da4f33baa553cb442d58defe81d98ec5e0806a66c0f79",
           "hostType": "docker",
           "username": "",
           "password": "",
           "method": "HEAD",
           "http2": false
         },
         "message": "Request failed with status code 401 (UNAUTHORIZED): HEAD https://quay.io/v2/org1/repo/manifests/sha256:4d657c3853d8c2d9005da4f33baa553cb442d58defe81d98ec5e0806a66c0f79",
         "stack": "HTTPError: Request failed with status code 401 (UNAUTHORIZED): HEAD https://**redacted**@14.6.6/node_modules/got/dist/source/as-promise/index.js:98:42)\n    at processTicksAndRejections (node:internal/process/task_queues:103:5)",
         "response": {
           "statusCode": 401,
           "statusMessage": "UNAUTHORIZED",
           "body": "",
           "headers": {
             "date": "Tue, 17 Mar 2026 08:40:02 GMT",
             "content-type": "application/json",
             "content-length": "112",
             "connection": "keep-alive",
             "server": "nginx",
             "www-authenticate": "Bearer realm=\"https://quay.io/v2/auth\",service=\"quay.io\",scope=\"repository:org1/repo:pull\"",
             "docker-distribution-api-version": "registry/2.0"
           },
           "httpVersion": "1.1",
           "retryCount": 0
         }
       }
DEBUG: getManifestResponse(https://quay.io, org1/repo, some-tag-2.0, head) (repository=myusername/reproducer, baseBranch=main)
DEBUG: HEAD https://quay.io/v2/org1/repo/manifests/some-tag-2.0 = (code=ERR_NON_2XX_3XX_RESPONSE, statusCode=401 retryCount=0, duration=242) (repository=myusername/reproducer, baseBranch=main)
DEBUG: Unauthorized docker lookup (repository=myusername/reproducer, baseBranch=main)
       "registryHost": "https://quay.io",
       "dockerRepository": "org1/repo"
DEBUG: Request failed with status code 401 (UNAUTHORIZED): HEAD https://quay.io/v2/org1/repo/manifests/some-tag-2.0 (repository=myusername/reproducer, baseBranch=main)
       "err": {
         "name": "HTTPError",
         "code": "ERR_NON_2XX_3XX_RESPONSE",
         "timings": {
           "start": 1773736803025,
           "socket": 1773736803025,
           "lookup": 1773736803025,
           "connect": 1773736803025,
           "secureConnect": 1773736803025,
           "upload": 1773736803025,
           "response": 1773736803267,
           "end": 1773736803267,
           "phases": {
             "wait": 0,
             "dns": 6,
             "tcp": 720,
             "tls": 222,
             "request": 0,
             "firstByte": 242,
             "download": 0,
             "total": 242
           }
         },
         "options": {
           "headers": {
             "user-agent": "Renovate/0.0.0-semantic-release (https://github.com/renovatebot/renovate)",
             "authorization": "***********",
             "accept": "application/vnd.docker.distribution.manifest.list.v2+json, application/vnd.docker.distribution.manifest.v2+json, application/vnd.oci.image.manifest.v1+json, application/vnd.oci.image.index.v1+json",
             "accept-encoding": "gzip, deflate, br, zstd"
           },
           "url": "https://quay.io/v2/org1/repo/manifests/some-tag-2.0",
           "hostType": "docker",
           "username": "",
           "password": "",
           "method": "HEAD",
           "http2": false
         },
         "message": "Request failed with status code 401 (UNAUTHORIZED): HEAD https://quay.io/v2/org1/repo/manifests/some-tag-2.0",
         "stack": "HTTPError: Request failed with status code 401 (UNAUTHORIZED): HEAD https://**redacted**@14.6.6/node_modules/got/dist/source/as-promise/index.js:98:42)\n    at processTicksAndRejections (node:internal/process/task_queues:103:5)",
         "response": {
           "statusCode": 401,
           "statusMessage": "UNAUTHORIZED",
           "body": "",
           "headers": {
             "date": "Tue, 17 Mar 2026 08:40:03 GMT",
             "content-type": "application/json",
             "content-length": "112",
             "connection": "keep-alive",
             "server": "nginx",
             "www-authenticate": "Bearer realm=\"https://quay.io/v2/auth\",service=\"quay.io\",scope=\"repository:org1/repo:pull\"",
             "docker-distribution-api-version": "registry/2.0"
           },
           "httpVersion": "1.1",
           "retryCount": 0
         }
       }
DEBUG: Could not determine new digest for update. (repository=myusername/reproducer, baseBranch=main)
       "packageName": "quay.io/org1/repo",
       "currentValue": "some-tag-2.0",
       "datasource": "docker",
       "newValue": "some-tag-2.0",
       "bucket": undefined
DEBUG: PackageFiles.add() - Package file saved for base branch (repository=myusername/reproducer, baseBranch=main)
DEBUG: Package releases lookups complete (repository=myusername/reproducer, baseBranch=main)
DEBUG: Repository libYears (repository=myusername/reproducer, baseBranch=main)
       "libYears": {"managers": {"dockerfile": 0}, "total": 0},
       "dependencyStatus": {"outdated": 0, "total": 1}
DEBUG: branchifyUpgrades (repository=myusername/reproducer, baseBranch=main)
DEBUG: detectSemanticCommits() (repository=myusername/reproducer, baseBranch=main)
DEBUG: getCommitMessages (repository=myusername/reproducer, baseBranch=main)
DEBUG: semanticCommits: detected "unknown" (repository=myusername/reproducer, baseBranch=main)
DEBUG: semanticCommits: disabled (repository=myusername/reproducer, baseBranch=main)
DEBUG: 0 flattened updates found:  (repository=myusername/reproducer, baseBranch=main)
DEBUG: Returning 0 branch(es) (repository=myusername/reproducer, baseBranch=main)
DEBUG: config.repoIsOnboarded=true (repository=myusername/reproducer, baseBranch=main)
DEBUG: packageFiles with updates (repository=myusername/reproducer, baseBranch=main)
       "config": {
         "dockerfile": [
           {
             "deps": [
               {
                 "depName": "quay.io/org1/repo",
                 "packageName": "quay.io/org1/repo",
                 "currentValue": "some-tag-2.0",
                 "currentDigest": "sha256:4d657c3853d8c2d9005da4f33baa553cb442d58defe81d98ec5e0806a66c0f79",
                 "replaceString": "quay.io/org1/repo:some-tag-2.0@sha256:4d657c3853d8c2d9005da4f33baa553cb442d58defe81d98ec5e0806a66c0f79",
                 "autoReplaceStringTemplate": "{{depName}}{{#if newValue}}:{{newValue}}{{/if}}{{#if newDigest}}@{{newDigest}}{{/if}}",
                 "datasource": "docker",
                 "depType": "final",
                 "updates": [],
                 "versioning": "docker",
                 "warnings": [
                   {
                     "message": "Could not determine new digest for update (docker package quay.io/org1/repo)",
                     "topic": "quay.io/org1/repo"
                   }
                 ]
               }
             ],
             "packageFile": "Dockerfile"
           }
         ]
       }
DEBUG: Branch summary (repository=myusername/reproducer)
       "cacheModified": undefined,
       "baseBranches": [{"branchName": "main", "sha": "df321d6857aac4c271356e1cd6eecd97f27d4f2b"}],
       "branches": [],
       "defaultBranch": "main",
       "inactiveBranches": []
DEBUG: Renovate repository PR statistics (repository=myusername/reproducer)
       "stats": {"total": 0, "open": 0, "closed": 0, "merged": 0}
DEBUG: Repository result: done, status: onboarded, enabled: true, onboarded: true (repository=myusername/reproducer)

[viceice]

the /v2/ is always inserted because the docker / oci API requires it.

did you tried to include it into your host rules?

[qixiang]

the /v2/ is always inserted because the docker / oci API requires it.

did you tried to include it into your host rules?

This is actually an implementation detail. Requiring users to understand this detail and then add the necessary /v2/ URLs based on it is not a reasonable approach.

And even with adding the /v2/ URLs, it won't work, because:

export async function getAuthHeaders(
  http: Http,
  registryHost: string,
  dockerRepository: string,
  apiCheckUrl = `${registryHost}/v2/`,
): Promise<OutgoingHttpHeaders | null> {
...
    const rule = hostRules.find({
      hostType: dockerDatasourceId,
      url: apiCheckUrl,
    });

hostRules.find is always called with the apiCheckUrl which is ${registryHost}/v2/, so the parsedUrl.href.startsWith(parsedMatchHost.href) (in matchesHost()) becomes:

"https://quay.io/v2/".startsWith("https://quay.io/v2/myorg/myrepo")

and always return false.

While the proposed fix calls:

      const repoUrl = `${registryHost}/${dockerRepository}`;
      const repoRule = hostRules.find({
        hostType: dockerDatasourceId,
        url: repoUrl,
      });

the url includes both the registry host and repo path, so it can work.

[qixiang]

Hi @viceice, do you mind me reopening #41967 ?

[viceice]

not yet. need to think about some side effects