feat(ENG-13681): add `cloudsmith domains list` with custom-domain discovery by cloudsmith-iduffy · Pull Request #337 · cloudsmith-io/cloudsmith-cli

cloudsmith-iduffy · 2026-08-01T13:22:08Z

Description

Adds cloudsmith domains list, which emits a versioned JSON document listing
the hosts Cloudsmith can authenticate — built-in *.cloudsmith.io service hosts
plus an organisation's custom domains.

Filters on the domain list.--format keeps the hosts usable for a package format: a host
serving no single format serves every one, so the download CDN and the
generic upload endpoint survive any --format. --repo keeps the hosts
usable for a repository, most-preferred first. --domain-type is an exact match instead — a host has
exactly one purpose — so pairing it with --format asks for a host
speaking a format's own protocol.
--org is the name of the organisation option.--organization and
--oidc-org remain as aliases, and org, organization or oidc_org are
all accepted in config.ini. --oidc-org named the setting after the first
feature that wanted it; custom-domain discovery reads it too, so it is now
named after what it is. CLOUDSMITH_ORG is unchanged, and
credential-helper install no longer carries a separate --org of its own.
A replaceable domain table. A dedicated deployment, serving packages from
its own domains, can replace the built-in hosts via a [domains] section in
config.ini. Each entry names the package format its host serves, or
download/upload for the two endpoints no format names; an entry naming
nothing recognisable is skipped with a warning rather than guessed at. This is
honoured only from trusted configuration — your config directory,
~/.cloudsmith, or an explicit --config-file. A [domains] section in a
directory-relative config.ini is ignored with a warning, because that file
can be committed to a repository and this list decides which hosts may receive
a credential.
Server-matching precedence between overlapping domains. A domain bound to
the repository in hand beats an organisation-wide one, primary beats
secondary, and the oldest breaks any remaining tie. With --repo the custom
domains come back most-preferred first, so the first entry is the one
Cloudsmith would bind for that repository.
A seven-day on-disk cache, with --refresh to bypass it
With no organisation configured, the command lists whatever custom domains an
earlier run already cached, at no API cost, rather than enumerating every
organisation the caller belongs to.

Type of Change

Emits a versioned JSON document naming the hosts Cloudsmith can authenticate - the built-in `*.cloudsmith.io` service hosts plus an organisation's custom domains - with the package format each serves and what each host is for (`download`, `upload`, `native_api`), so a consumer picks a host without pattern-matching on hostnames. Like `credential-helper generic` it is for programmatic consumers and has no human-readable mode. An organisation's own custom domains are listed ahead of the built-in hosts, which are the fallback. Only usable hosts are listed: a custom domain that is disabled or not yet validated serves nothing, so it is left out rather than offered as somewhere to publish to. `--format`, `--repo` and `--domain-type` narrow the list; with `--repo` the custom domains come back most-preferred first, so the first entry is the one Cloudsmith would bind. Alongside it: - `--org` is the name of the organisation option, with `--organization` and `--oidc-org` as aliases and `org`, `organization` or `oidc_org` accepted in config.ini. `--oidc-org` named the setting after the first feature that wanted it; custom-domain discovery reads it too. CLOUDSMITH_ORG is unchanged, and `credential-helper install` no longer carries its own --org. - A dedicated deployment serving packages from its own domains can replace the built-in table via a `[domains]` section in config.ini, honoured only from trusted configuration - your config directory, ~/.cloudsmith, or an explicit --config-file. A section in a directory-relative config.ini is ignored with a warning, since that file can be committed to a repository and this table decides which hosts may receive a credential. - Custom domain records carry the organisation they were discovered under and, where the domain serves a single repository, which one. Overlapping domains are ranked as the server would: bound to the repository in hand, then primary, then oldest. - A seven-day on-disk cache, with `--refresh` to bypass it. No failure is ever cached, so a typo'd organisation fails loudly every time rather than being replayed as a successful "no custom domains". With no organisation configured the command lists what earlier runs cached, at no API cost. Also fixed: `ApiException` was built without passing anything to `Exception`, so rendering one as a string produced nothing at all and any message built by interpolation stopped dead at the colon. It now renders as its status plus the API's detail, which fixes the custom-domain lookup message along with the `credential-helper install`/`uninstall` failures and the Docker auto-discovery warning. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Copilot

Pull request overview

Adds a new cloudsmith domains list command to emit a versioned JSON document of Cloudsmith-authenticatable hosts (built-in service hosts plus org custom domains), and renames the organization setting to a unified --org (with aliases) so custom-domain discovery and OIDC exchange share the same configuration surface.

Changes:

Introduces cloudsmith domains list with filtering (--format, --repo, --domain-type) and a cache-backed custom-domain lookup.
Adds a trusted-config override for the built-in domain table via a [domains] section, while explicitly rejecting cwd config.ini for security.
Unifies organization configuration under --org/CLOUDSMITH_ORG/config.ini (org|organization|oidc_org) and threads it through credential-helper flows.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
cloudsmith_cli/credential_helpers/docker/runtime.py	Threads `org` into Docker credential helper runtime matching.
cloudsmith_cli/credential_helpers/docker/installer.py	Adjusts Docker installer discovery logic for custom domains.
cloudsmith_cli/credential_helpers/default_domains.py	Adds built-in domain table with trusted-config override and untrusted-cwd guard.
cloudsmith_cli/credential_helpers/custom_domains.py	Expands custom-domain records, precedence ordering, and cache format/versioning.
cloudsmith_cli/credential_helpers/common.py	Updates Cloudsmith-domain matching to accept resolved `org` rather than reading env directly.
cloudsmith_cli/credential_helpers/backends.py	Adds `NIX` backend kind.
cloudsmith_cli/core/credentials/providers/oidc_provider.py	Switches OIDC provider to use unified `context.org`.
cloudsmith_cli/core/credentials/models.py	Renames credential context field from `oidc_org` to `org`.
cloudsmith_cli/core/api/exceptions.py	Improves `ApiException` string rendering for clearer error messages.
cloudsmith_cli/conftest.py	Adds an autouse fixture to restore SDK default configuration between tests.
cloudsmith_cli/cli/tests/test_org_option.py	Tests `--org` and config/env aliases all map to one organization value.
cloudsmith_cli/cli/tests/commands/test_domains.py	Adds test coverage for `cloudsmith domains list` document shape and filters.
cloudsmith_cli/cli/tests/commands/test_default_domains.py	Tests built-in domain table plus trusted/untrusted config override behavior.
cloudsmith_cli/cli/tests/commands/test_custom_domain_precedence.py	Tests precedence ordering and cache survivability of ranking fields.
cloudsmith_cli/cli/tests/commands/test_credential_helper.py	Updates credential-helper tests for new cache format and org threading.
cloudsmith_cli/cli/tests/commands/test_credential_helper_install.py	Updates installer tests for revised discovery behavior and org handling.
cloudsmith_cli/cli/decorators.py	Adds `--org/--organization/--oidc-org` aliasing and threads `org` into credential resolution.
cloudsmith_cli/cli/config.py	Adds `org`/`organization` config keys and maps legacy `oidc_org` to the same value.
cloudsmith_cli/cli/commands/domains.py	Implements `cloudsmith domains list` command and JSON document output.
cloudsmith_cli/cli/commands/credential_helper/manage.py	Removes installer-specific `--org` and relies on shared resolved `opts.org`.
cloudsmith_cli/cli/commands/credential_helper/docker.py	Passes resolved `opts.org` through to Docker credential helper execution.
cloudsmith_cli/cli/commands/init.py	Registers the new `domains` command module.
CHANGELOG.md	Documents new domains command, org rename/aliasing, and `[domains]` override feature.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Review of `domains list` and the custom-domain path it shares with the credential helpers turned up three defects. - Restored the `dry_run` short-circuit ahead of discovery, and the two test scenarios deleted with it. A preview was issuing a live authenticated call and rewriting the on-disk cache. - Custom domains are ranked by precedence whether or not `--repo` is given, so the document agrees with `get_format_domains` about which host is active. Records from a no-org listing are grouped by org first, since ranking one organisation's hosts against another's expressed a preference the server never made. A missing `created_at` sorted as the empty string, i.e. older than every real timestamp, so the one domain whose age is unknown won precedence. - Creating the cache directory is no longer fatal, so `domains list` still answers on a read-only HOME as its "always listed" promise implies. `UnicodeDecodeError` escaped both readers, which catch `JSONDecodeError` and `configparser.Error`; one corrupt cache file or a config.ini in a non-UTF-8 locale aborted the command instead of reading as absent. Also: dropped `DomainType.API`. No domain is ever the Cloudsmith API, so the value only ever matched nothing while being advertised as a valid purpose. `get_format_domains` now forwards `configure_api` like its siblings. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

BartoszBlizniak

one nit but lgtm

Add the same --page/--page-size/--page-all options other `list` commands use, applied client-side to the combined built-in + custom domain list. Unlike other commands it defaults to --page-all since the list is small and locally assembled rather than backed by a live paginated endpoint; passing --page or --page-size opts into paged output with a `meta.pagination` block matching other JSON list output. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

github-advanced-securityAI found potential problems Aug 1, 2026
View reviewed changes

Comment threadcloudsmith_cli/cli/tests/commands/test_domains.py Fixed
Comment threadcloudsmith_cli/cli/tests/commands/test_domains.py Fixed
Comment threadcloudsmith_cli/cli/tests/commands/test_domains.py Fixed

cloudsmith-iduffy changed the title ~~custom domains~~feat(ENG-13681): add credential-helper domains with repository-scoped custom domainsAug 1, 2026

This was referenced Aug 1, 2026
feat(ENG-13681): add credential-helper generic command #338
Merged
feat(ENG-13683): add Maven credential helper #339
Open

BartoszBlizniak mentioned this pull request Aug 3, 2026
release: cloudsmith-cli v1.21.0 #343
Merged
6 tasks

BartoszBlizniak force-pushed the custom-domains branch from f5b0924 to 8ed90e7Compare August 4, 2026 08:36

cloudsmith-iduffy mentioned this pull request Aug 4, 2026
refactor(no-ticket): pass resolved credentials through credential-helper plumbing #336
Merged
6 tasks

Base automatically changed from credential-plumbing to masterAugust 4, 2026 15:37