feat: add OIDC detector enable/order controls

Add two env-var controls for OIDC detector selection:

- CLOUDSMITH_OIDC_<DETECTOR>_DISABLED skips a specific detector,
  mirroring boto3's AWS_EC2_METADATA_DISABLED convention (only the
  literal "true", case-insensitive, disables).
- CLOUDSMITH_OIDC_DETECTOR_ORDER overrides which detectors are
  considered and the order they are tried in (comma-separated slugs;
  unlisted/unknown slugs are skipped).

When both are set the order list defines the candidate set and
sequence, then the disable flags are applied on top, so a disabled
detector is always skipped. Each detector gains a stable `slug`
attribute and a public `registered_detectors()` accessor is added.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: cloudsmith-iduffy

CHANGELOG.md

@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Added GitLab CI to OIDC credential auto-discovery. When running in GitLab CI/CD, the CLI reads the OIDC token from the `CLOUDSMITH_OIDC_TOKEN` environment variable (configured via `id_tokens` in `.gitlab-ci.yml`, with legacy fallbacks to `CI_JOB_JWT_V2` / `CI_JOB_JWT`) and exchanges it for a Cloudsmith access token. Works out of the box with no extra dependencies.
 - Added Google Cloud (GCP) support to OIDC credential auto-discovery. Install with the `gcp` extra (`pip install cloudsmith-cli[gcp]`) to authenticate using the ambient Google Cloud identity: the attached service account on GCE/Cloud Run/GKE/Cloud Functions/App Engine/Cloud Build, a `GOOGLE_APPLICATION_CREDENTIALS` service-account key, or a local `gcloud auth application-default login` session. The CLI discovers credentials via the `google-auth` SDK's Application Default Credentials chain, mints a short-lived OIDC ID token, and exchanges it for a Cloudsmith access token. On Cloud Build, where the metadata server exposes no ID-token endpoint, the token is minted via the IAM Credentials API (`generateIdToken`), which requires the build service account to hold `roles/iam.serviceAccountTokenCreator` on itself. Without the extra installed, the detector skips itself with no errors.
 - Added a generic fallback to OIDC credential auto-discovery. When no dedicated environment is detected, the CLI reads an OIDC token from the `CLOUDSMITH_OIDC_TOKEN` environment variable (useful for Jenkins or any custom CI/CD) and exchanges it for a Cloudsmith access token. Works out of the box with no extra dependencies.
+- Added controls for OIDC detector selection. Set `CLOUDSMITH_OIDC_<DETECTOR>_DISABLED=true` to skip a specific detector (mirroring boto3's `AWS_EC2_METADATA_DISABLED` convention — only `true` disables), or `CLOUDSMITH_OIDC_DETECTOR_ORDER` to a comma-separated list of detector slugs to override which detectors are considered and the order they are tried in. When both are set, disable flags take precedence over the order list. Detector slugs: `aws`, `azure_devops`, `bitbucket`, `circleci`, `gcp`, `generic`, `github`, `gitlab`.
 
 ## [1.18.0] - 2026-06-09
 

README.md

@@ -229,6 +229,15 @@ See the [Cloudsmith GitLab CI/CD integration guide](https://docs.cloudsmith.com/
 
 As a fallback for environments without a dedicated detector (for example Jenkins with the [credentials binding plugin](https://plugins.jenkins.io/credentials-binding/), or any custom CI/CD system), set the `CLOUDSMITH_OIDC_TOKEN` environment variable to an OIDC JWT and the CLI will exchange it for a Cloudsmith access token. This detector runs last, so a dedicated environment is always preferred when present. See the [Cloudsmith Jenkins OIDC guide](https://docs.cloudsmith.com/authentication/setup-jenkins-to-authenticate-to-cloudsmith-using-oidc).
 
+#### Controlling OIDC Detector Selection
+
+By default the CLI tries each detector in a fixed priority order and uses the first that matches. Two environment variables let you override this when a detector matches an environment you don't want it to (for example, the AWS detector matching ambient instance credentials):
+
+- **Disable a detector** — set `CLOUDSMITH_OIDC_<DETECTOR>_DISABLED=true` to skip it entirely. This mirrors boto3's `AWS_EC2_METADATA_DISABLED` convention: only the literal value `true` (case-insensitive) disables; anything else leaves the detector enabled. For example, `CLOUDSMITH_OIDC_AWS_DISABLED=true` skips the AWS detector so an explicitly-set `CLOUDSMITH_OIDC_TOKEN` is picked up by the generic detector instead.
+- **Reorder evaluation** — set `CLOUDSMITH_OIDC_DETECTOR_ORDER` to a comma-separated list of detector slugs to control both which detectors are considered and the order they are tried in (first match wins). Slugs not listed are skipped; unrecognised slugs are ignored. For example, `CLOUDSMITH_OIDC_DETECTOR_ORDER=generic,aws` tries the generic detector first and considers only those two.
+
+When both are set, the order list defines the candidate set and sequence, then the `*_DISABLED` flags are applied on top — so a disabled detector is always skipped even if it appears in the order list. Detector slugs are: `aws`, `azure_devops`, `bitbucket`, `circleci`, `gcp`, `generic`, `github`, `gitlab`.
+
 ## Configuration
 
 There are two configuration files used by the CLI:

cloudsmith_cli/core/credentials/oidc/detectors/__init__.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+import os
 from typing import TYPE_CHECKING
 
 from .aws import AWSDetector
@@ -31,12 +32,70 @@
     GenericDetector,
 ]
 
+DETECTOR_ORDER_ENV_VAR = "CLOUDSMITH_OIDC_DETECTOR_ORDER"
+
+
+def registered_detectors() -> list[type[EnvironmentDetector]]:
+    """Return the registered OIDC detectors in their default priority order."""
+    return list(_DETECTORS)
+
+
+def _disable_env_var(slug: str) -> str:
+    return f"CLOUDSMITH_OIDC_{slug.upper()}_DISABLED"
+
+
+def _is_detector_disabled(slug: str) -> bool:
+    """Whether a detector is disabled via its CLOUDSMITH_OIDC_<SLUG>_DISABLED var.
+
+    Mirrors boto3's ``AWS_EC2_METADATA_DISABLED`` wording: only the literal
+    string ``true`` (case-insensitive) disables; anything else is off.
+    """
+    return os.environ.get(_disable_env_var(slug), "false").strip().lower() == "true"
+
+
+def _ordered_detectors() -> list[type[EnvironmentDetector]]:
+    """Detectors in evaluation order, honouring CLOUDSMITH_OIDC_DETECTOR_ORDER.
+
+    When the order var is unset/empty the default registration order is used.
+    Otherwise only the listed slugs are considered, in the listed order;
+    unknown slugs are logged and skipped.
+    """
+    raw_order = os.environ.get(DETECTOR_ORDER_ENV_VAR, "").strip()
+    if not raw_order:
+        return list(_DETECTORS)
+
+    detectors_by_slug = {detector_cls.slug: detector_cls for detector_cls in _DETECTORS}
+    ordered: list[type[EnvironmentDetector]] = []
+    for token in raw_order.split(","):
+        slug = token.strip().lower()
+        if not slug:
+            continue
+        detector_cls = detectors_by_slug.get(slug)
+        if detector_cls is None:
+            logger.debug(
+                "Ignoring unknown OIDC detector slug in %s: %s",
+                DETECTOR_ORDER_ENV_VAR,
+                slug,
+            )
+            continue
+        ordered.append(detector_cls)
+    return ordered
+
+
+def _enabled_detectors() -> list[type[EnvironmentDetector]]:
+    """Ordered detectors with disabled ones removed (disable always wins)."""
+    return [
+        detector_cls
+        for detector_cls in _ordered_detectors()
+        if not _is_detector_disabled(detector_cls.slug)
+    ]
+
 
 def detect_environment(
     context: CredentialContext,
 ) -> EnvironmentDetector | None:
     """Try each detector in order, returning the first that matches."""
-    for detector_cls in _DETECTORS:
+    for detector_cls in _enabled_detectors():
         detector = detector_cls(context=context)
         try:
             if detector.detect():

cloudsmith_cli/core/credentials/oidc/detectors/aws.py

@@ -22,6 +22,7 @@ class AWSDetector(EnvironmentDetector):
     """Detects AWS environments and obtains a JWT via STS GetWebIdentityToken."""
 
     name = "AWS"
+    slug = "aws"
 
     def __init__(self, context):
         super().__init__(context)

cloudsmith_cli/core/credentials/oidc/detectors/azure_devops.py

@@ -30,6 +30,7 @@ class AzureDevOpsDetector(EnvironmentDetector):
     """Detects Azure DevOps and fetches an OIDC token via HTTP POST."""
 
     name = "Azure DevOps"
+    slug = "azure_devops"
 
     def detect(self) -> bool:
         return bool(os.environ.get("SYSTEM_OIDCREQUESTURI")) and bool(

cloudsmith_cli/core/credentials/oidc/detectors/base.py

@@ -14,6 +14,7 @@ class EnvironmentDetector:
     """Base class for OIDC environment detectors."""
 
     name: str = "base"
+    slug: str = "base"
 
     def __init__(self, context: CredentialContext):
         self.context = context

cloudsmith_cli/core/credentials/oidc/detectors/bitbucket_pipelines.py

@@ -20,6 +20,7 @@ class BitbucketPipelinesDetector(EnvironmentDetector):
     """Detects Bitbucket Pipelines and reads its OIDC token from environment."""
 
     name = "Bitbucket Pipelines"
+    slug = "bitbucket"
 
     def detect(self) -> bool:
         return bool(os.environ.get("BITBUCKET_STEP_OIDC_TOKEN"))

cloudsmith_cli/core/credentials/oidc/detectors/circleci.py

@@ -20,6 +20,7 @@ class CircleCIDetector(EnvironmentDetector):
     """Detects CircleCI and reads OIDC token from environment variable."""
 
     name = "CircleCI"
+    slug = "circleci"
 
     def detect(self) -> bool:
         return os.environ.get("CIRCLECI") == "true" and bool(

cloudsmith_cli/core/credentials/oidc/detectors/gcp.py

@@ -28,6 +28,7 @@ class GCPDetector(EnvironmentDetector):
     """Detects Google Cloud environments and obtains an OIDC ID token."""
 
     name = "Google Cloud"
+    slug = "gcp"
 
     def __init__(self, context):
         super().__init__(context)

cloudsmith_cli/core/credentials/oidc/detectors/generic.py

@@ -27,6 +27,7 @@ class GenericDetector(EnvironmentDetector):
     """
 
     name = "Generic"
+    slug = "generic"
 
     def detect(self) -> bool:
         return bool((os.environ.get(TOKEN_ENV_VAR) or "").strip())