Sandboxes: document precedence for overlapping service and custom credentials #26390

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

I can't find what I'm looking for

Description

The credentials guide explains service-based credential injection and custom-secret placeholder replacement separately, but does not explain how they interact when both target the same host and request header.

For example, a local sandbox might have a built-in github service secret for read-only access and a custom secret for a different token intended to write to one repository. Both target github.com and api.github.com, and a request can contain the custom placeholder in its Authorization header.

The documented precedence between credential sources for the same service does not establish precedence between a service-secret injection rule and custom-secret substitution. Readers cannot tell which credential will be sent, whether substitution and header replacement have a defined order, or whether an agent can select between credentials per request.

Location

• https://docs.docker.com/ai/sandboxes/configuration/credentials/#how-credential-injection-works
• https://docs.docker.com/ai/sandboxes/configuration/credentials/#custom-secrets

Suggestion

Document the supported behavior for overlapping credentials in local sandboxes:

• Which credential is used when a service rule and a custom secret match the same host and header, including when the request contains a custom placeholder.
• How global and sandbox-scoped credentials affect that result. Distinguish same-service scope precedence from collisions between different credential mechanisms.
• Whether two custom secrets can target the same host and how their placeholders select a credential, if supported.
• Whether per-request selection between a built-in service credential and a custom credential is supported. If it is not, state the limitation and show a supported alternative for workflows requiring different credentials.

Add a small precedence table and a tested example using read-only and repository-specific write credentials. Explain which requests receive each credential without exposing real token values. Confirm the behavior with the implementation; do not infer collision precedence from the existing same-service precedence statement. State local/cloud differences where relevant.