feat: add CircleCI OIDC detector

Reads the OIDC token from CIRCLE_OIDC_TOKEN_V2 (preferred) or
CIRCLE_OIDC_TOKEN when running in CircleCI, and registers the detector
in the auto-discovery chain.

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

Author: cloudsmith-iduffy

CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+### Added
+
+- Added CircleCI to OIDC credential auto-discovery. When running in CircleCI, the CLI reads the OIDC token from the `CIRCLE_OIDC_TOKEN_V2` (preferred) or `CIRCLE_OIDC_TOKEN` environment variable and exchanges it for a Cloudsmith access token.
+
 ## [1.17.0] - 2026-05-18
 
 ### Added

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

@@ -7,13 +7,15 @@
 
 from .aws import AWSDetector
 from .base import EnvironmentDetector
+from .circleci import CircleCIDetector
 
 if TYPE_CHECKING:
     from ... import CredentialContext
 
 logger = logging.getLogger(__name__)
 
 _DETECTORS: list[type[EnvironmentDetector]] = [
+    CircleCIDetector,
     AWSDetector,
 ]
 

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

@@ -0,0 +1,35 @@
+"""CircleCI OIDC detector.
+
+Reads OIDC token from the ``CIRCLE_OIDC_TOKEN_V2`` or ``CIRCLE_OIDC_TOKEN``
+environment variables set by CircleCI's OIDC support.
+
+References:
+    https://circleci.com/docs/guides/permissions-authentication/openid-connect-tokens/
+    https://docs.cloudsmith.com/integrations/integrating-with-circleci
+"""
+
+from __future__ import annotations
+
+import os
+
+from .base import EnvironmentDetector
+
+
+class CircleCIDetector(EnvironmentDetector):
+    """Detects CircleCI and reads OIDC token from environment variable."""
+
+    name = "CircleCI"
+
+    def detect(self) -> bool:
+        return os.environ.get("CIRCLECI") == "true" and bool(
+            os.environ.get("CIRCLE_OIDC_TOKEN_V2")
+            or os.environ.get("CIRCLE_OIDC_TOKEN")
+        )
+
+    def get_token(self) -> str:
+        token = os.environ.get("CIRCLE_OIDC_TOKEN_V2") or os.environ.get(
+            "CIRCLE_OIDC_TOKEN"
+        )
+        if not token:
+            raise ValueError("CircleCI detected but CIRCLE_OIDC_TOKEN not set")
+        return token

cloudsmith_cli/core/tests/test_circleci_detector.py

@@ -0,0 +1,69 @@
+"""Tests for the CircleCI OIDC detector."""
+
+from unittest import mock
+
+import pytest
+
+from cloudsmith_cli.core.credentials.models import CredentialContext
+from cloudsmith_cli.core.credentials.oidc.detectors.circleci import CircleCIDetector
+
+
+@pytest.fixture
+def circleci_env():
+    env = {
+        "CIRCLECI": "true",
+        "CIRCLE_OIDC_TOKEN_V2": "the-v2-jwt",
+        "CIRCLE_OIDC_TOKEN": "the-v1-jwt",
+    }
+    with mock.patch.dict("os.environ", env, clear=True):
+        yield env
+
+
+class TestDetect:
+    def test_detects_when_circleci_and_v2_token_present(self, circleci_env):
+        detector = CircleCIDetector(context=CredentialContext())
+        assert detector.detect() is True
+
+    def test_detects_with_only_v1_token(self, circleci_env):
+        del circleci_env["CIRCLE_OIDC_TOKEN_V2"]
+        with mock.patch.dict("os.environ", circleci_env, clear=True):
+            detector = CircleCIDetector(context=CredentialContext())
+            assert detector.detect() is True
+
+    def test_not_detected_when_unset(self):
+        with mock.patch.dict("os.environ", {}, clear=True):
+            detector = CircleCIDetector(context=CredentialContext())
+            assert detector.detect() is False
+
+    def test_not_detected_when_circleci_flag_missing(self, circleci_env):
+        del circleci_env["CIRCLECI"]
+        with mock.patch.dict("os.environ", circleci_env, clear=True):
+            detector = CircleCIDetector(context=CredentialContext())
+            assert detector.detect() is False
+
+    def test_not_detected_without_any_token(self, circleci_env):
+        del circleci_env["CIRCLE_OIDC_TOKEN_V2"]
+        del circleci_env["CIRCLE_OIDC_TOKEN"]
+        with mock.patch.dict("os.environ", circleci_env, clear=True):
+            detector = CircleCIDetector(context=CredentialContext())
+            assert detector.detect() is False
+
+
+class TestGetToken:
+    def test_prefers_v2_token(self, circleci_env):
+        detector = CircleCIDetector(context=CredentialContext())
+        assert detector.get_token() == "the-v2-jwt"
+
+    def test_falls_back_to_v1_token(self, circleci_env):
+        del circleci_env["CIRCLE_OIDC_TOKEN_V2"]
+        with mock.patch.dict("os.environ", circleci_env, clear=True):
+            detector = CircleCIDetector(context=CredentialContext())
+            assert detector.get_token() == "the-v1-jwt"
+
+    def test_raises_when_no_token(self, circleci_env):
+        del circleci_env["CIRCLE_OIDC_TOKEN_V2"]
+        del circleci_env["CIRCLE_OIDC_TOKEN"]
+        with mock.patch.dict("os.environ", circleci_env, clear=True):
+            detector = CircleCIDetector(context=CredentialContext())
+            with pytest.raises(ValueError):
+                detector.get_token()