Skip to content

Update RegistryAuthentication.md #634

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
baronfel wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update RegistryAuthentication.md #634

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b10e59b
Update RegistryAuthentication.md
baronfel Jun 5, 2025
5cc4c13
Update RegistryAuthentication.md
baronfel Jun 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 16 additions & 3 deletions docs/RegistryAuthentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,16 +29,29 @@ The `credsStore` section is a single string property whose value is the name of

In some scenarios the standard Docker authentication mechanism described above just doesn't cut it. This tooling has an additional mechanism for providing credentials to registries: environment variables. If environment variables are used, the credential provide mechanism will not be used at all. The following environment variables are supported:

_Preferred_

* DOTNET_CONTAINER_PUSH_REGISTRY_UNAME
* This should be the username for the _destination_ registry. If the password for the registry is a token, then the username should be `"<token>"`.
* DOTNET_CONTAINER_PUSH_REGISTRY_PWORD
* This should be the password, token, etc for the _destination_ registry.

* DOTNET_CONTAINER_PULL_REGISTRY_UNAME
* This should be the username for the _source_ registry. If the password for the registry is a token, then the username should be `"<token>"`.
* DOTNET_CONTAINER_PULL_REGISTRY_PWORD
* This should be the password, token, etc for the _source_ registry.

_Supported but not recommended_

@mthalman mthalman Apr 13, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we document the precedence behavior when both sets of variables are set?

@baronfel baronfel Apr 13, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's:

  • preferred variants always supersede the older variants if present
  • both username and password must come from the same 'variant'

So

DOTNET_CONTAINER_PUSH_REGISTRY_UNAME=...
DOTNET_CONTAINER_PUSH_REGISTRY_PWORD=...
DOTNET_CONTAINER_REGISTRY_UNAME=....
DOTNET_CONTAINER_REGISTRY_PWORD=....

would use DOTNET_CONTAINER_PUSH_REGISTRY_UNAME/DOTNET_CONTAINER_PUSH_REGISTRY_PWORD for the Push side of any operations, and
DOTNET_CONTAINER_REGISTRY_UNAME/DOTNET_CONTAINER_REGISTRY_PWORD for the Pull side of any operations.

* DOTNET_CONTAINER_REGISTRY_UNAME
* This should be the username for the registry. If the password for the registry is a token, then the username should be `"<token>"`.
* DOTNET_CONTAINER_REGISTRY_PWORD
* This should be the password, token, etc for the registry.

> [!NOTE]
> As of .NET SDK 8.0.400, the environment variables for container operations have been updated.
> `SDK_CONTAINER_*` variables are now prefixed with `DOTNET_CONTAINER_*`. Please use the old prefixes in your configuration files or scripts.
> The not recommended environment variables aren't namespaced - the SDK will attempt to use the same credentials for both the 'source' registry (where your base image is located) as well as the 'destination' registry (where you are pushing your final image). This is why we prefer the usage of the separate PUSH and PULL variables.

This mechanism is potentially vulnerable to credential leakage, so it should only be used in scenarios where the other mechanism is not available. For example, if you are using the SDK Container tooling inside a Docker container itself. In addition, this mechanism isn't namespaced - it will attempt to use the same credentials for both the 'source' registry (where your base image is located) as well as the 'destination' registry (where you are pushing your final image).
> [!NOTE]
> All environment-variable based usage is vulnerable to credential leakage as other processes or build logic may be able to access the environment variables of the SDK process. We recommend using the credential helper-based approaches listed above for this reason.

## Known-supported registries

Expand Down