[cloudsmith-iduffy]

Description

credHelpers in ~/.docker/config.json holds only a helper name, and Docker runs the helper with the environment of the Docker client. So a CLOUDSMITH_PROFILE=meta cloudsmith credential-helper install docker was forgotten on the next pull from Docker Desktop, an IDE or a new terminal (ENG-15016).

The Docker installer now keeps the install-time settings in its launcher (see #511). An install with a profile or a Workspace also gets its own helper:

Install	Launcher	credHelpers value
no profile or Workspace	docker-credential-cloudsmith	cloudsmith
-P meta	docker-credential-cloudsmith-meta	cloudsmith-meta
-w acme	docker-credential-cloudsmith-acme	cloudsmith-acme
both	docker-credential-cloudsmith-meta-acme	cloudsmith-meta-acme

• An install without a profile or a Workspace writes the same names as before. A scoped install does not touch the launcher of an earlier version.
• credHelpers maps one host to one helper, so a host that two installs configure, such as docker.cloudsmith.io, uses the last install. The install shows a warning when it moves a host from a different Cloudsmith helper.
• uninstall docker -P meta -w acme removes only that helper. A -P on the root command (cloudsmith -P meta credential-helper uninstall …) also counts. The scope comes only from flags, so a plain uninstall docker removes the unscoped helper as before, also in a shell that sets CLOUDSMITH_WORKSPACE.
• Two scopes can give the same name. Install and uninstall read the profile and the Workspace from the existing launcher, and stop if they differ. The error shows the uninstall command for that launcher.
• list shows the hosts of every cloudsmith and cloudsmith-* helper, and the launcher that they use.
• --dry-run shows the scoped launcher and the names of the settings that it keeps.

The ticket proposed CLI flags in the launcher. I used environment variables instead, so Docker and NuGet share one mechanism and the keyring settings, which have no flags, are kept too.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring
• Other (please describe)

Additional Notes

Testing. I ran a live docker pull of a private image on docker.cloudsmith.io with only a SAML session. A temporary config.ini sent the default profile to an API host with no SAML session, and profile e2e to api.cloudsmith.io. I installed with CLOUDSMITH_PROFILE=e2e, CLOUDSMITH_WORKSPACE and CLOUDSMITH_CONFIG_FILE into a temporary DOCKER_CONFIG and bin directory. Then:

• env -i … docker pull with no CLOUDSMITH_* variables worked.
• The same pull with CLOUDSMITH_PROFILE=default CLOUDSMITH_WORKSPACE=other in the caller environment also worked.
• Without the helper, the pull failed with unauthorized.
• uninstall docker -P e2e -w <workspace> removed the launcher and the credHelpers entry.

Known limits.

• The name segments are sanitized to [a-z0-9-], so -P acme and -w acme both give cloudsmith-acme. These two installs cannot exist together: the second one stops with an error. Two installs that differ only in --api-host share a name, and the last install wins. The ticket suggested a hash suffix for this. I left it out, because it makes the names hard to predict and to uninstall.
• list shows one launcher for the Docker hosts, also when they use different helpers.
• The proxy and the colour settings are never written. Behind a proxy, set CLOUDSMITH_PROXY or HTTPS_PROXY where Docker runs.
• The pnpm and cargo launchers do not keep install-time settings yet.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Helper-name collisions and ignored root-level profile flags can overwrite or remove the wrong installation.

2 open issues

• Honor root profile flag when uninstalling credential helpers · New
• Prevent helper name collisions across profile and workspace scopes · New

What changed in this PR

Preserves install-time settings in Docker credential helpers so they behave consistently across shells, IDEs, and Docker Desktop.

Changes:

• Adds profile/workspace-scoped launchers with persisted settings.
• Supports scoped uninstall and status reporting.
• Adds regression tests and changelog documentation.

File	Description
cloudsmith_cli/​credential_helpers/​docker/​installer.py	Persists settings and manages scoped helpers.
cloudsmith_cli/​cli/​tests/​commands/​test_credential_helper_install.py	Tests scoped installation, dry runs, removal, and status.
cloudsmith_cli/​cli/​commands/​credential_helper/​manage.py	Passes explicit uninstall scope to Docker.
CHANGELOG.md	Documents settings persistence and scoped helper behavior.

_{Review effort: Balanced}