feat: add GitLab CI OIDC detector

Add GitLab CI to OIDC credential auto-discovery. When running in GitLab
CI/CD, the CLI reads the OIDC token from CLOUDSMITH_OIDC_TOKEN (configured
via id_tokens in .gitlab-ci.yml, with legacy fallbacks to CI_JOB_JWT_V2 and
CI_JOB_JWT) and exchanges it for a Cloudsmith access token. Works out of the
box with no extra dependencies.

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 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.
+
 ## [1.17.0] - 2026-05-18
 
 ### Added

README.md

@@ -165,6 +165,21 @@ pip install cloudsmith-cli[all]
 
 **Note:** If you don't install the AWS extra, the AWS OIDC detector will gracefully skip itself with no errors.
 
+#### GitLab CI OIDC Support
+
+In GitLab CI/CD, OIDC credential discovery works out of the box with no extra dependencies. Configure an [`id_tokens`](https://docs.gitlab.com/ci/cloud_services/) entry in your `.gitlab-ci.yml` with an `aud` of `https://api.cloudsmith.io/openid/<your-org>` and expose it as `CLOUDSMITH_OIDC_TOKEN`, and the CLI will pick it up automatically:
+
+```yaml
+job:
+  id_tokens:
+    CLOUDSMITH_OIDC_TOKEN:
+      aud: https://api.cloudsmith.io/openid/<your-org>
+  script:
+    - cloudsmith push ...
+```
+
+See the [Cloudsmith GitLab CI/CD integration guide](https://docs.cloudsmith.com/integrations/integrating-with-gitlab-cicd).
+
 ## Configuration
 
 There are two configuration files used by the CLI:

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

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

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

@@ -0,0 +1,46 @@
+# Copyright 2026 Cloudsmith Ltd
+"""GitLab CI OIDC detector.
+
+Reads an OIDC token from environment variables populated by GitLab's
+``id_tokens`` configuration in ``.gitlab-ci.yml``.
+
+References:
+    https://docs.gitlab.com/ci/cloud_services/
+    https://docs.cloudsmith.com/integrations/integrating-with-gitlab-cicd
+"""
+
+from __future__ import annotations
+
+import os
+
+from .base import EnvironmentDetector
+
+
+class GitLabCIDetector(EnvironmentDetector):
+    """Detects GitLab CI and reads an OIDC token from an environment variable.
+
+    GitLab requires users to configure ``id_tokens`` in ``.gitlab-ci.yml``.
+    The token is exposed as an environment variable with a user-chosen name.
+    We check common conventions in priority order: ``CLOUDSMITH_OIDC_TOKEN``,
+    ``CI_JOB_JWT_V2``, ``CI_JOB_JWT``.
+    """
+
+    name = "GitLab CI"
+
+    TOKEN_ENV_VARS = ["CLOUDSMITH_OIDC_TOKEN", "CI_JOB_JWT_V2", "CI_JOB_JWT"]
+
+    def detect(self) -> bool:
+        if os.environ.get("GITLAB_CI") != "true":
+            return False
+        return any(os.environ.get(var) for var in self.TOKEN_ENV_VARS)
+
+    def get_token(self) -> str:
+        for var in self.TOKEN_ENV_VARS:
+            token = os.environ.get(var)
+            if token:
+                return token
+        raise ValueError(
+            "GitLab CI detected but no OIDC token found. "
+            "Configure id_tokens in .gitlab-ci.yml and set one of: "
+            + ", ".join(self.TOKEN_ENV_VARS)
+        )

cloudsmith_cli/core/tests/test_gitlab_ci_detector.py

@@ -0,0 +1,87 @@
+"""Tests for the GitLab CI OIDC detector."""
+
+from unittest import mock
+
+import pytest
+
+from cloudsmith_cli.core.credentials.models import CredentialContext
+from cloudsmith_cli.core.credentials.oidc.detectors import detect_environment
+from cloudsmith_cli.core.credentials.oidc.detectors.gitlab_ci import GitLabCIDetector
+
+
+@pytest.fixture
+def gitlab_env():
+    env = {
+        "GITLAB_CI": "true",
+        "CLOUDSMITH_OIDC_TOKEN": "the-jwt",
+    }
+    with mock.patch.dict("os.environ", env, clear=True):
+        yield env
+
+
+class TestDetect:
+    def test_detects_when_gitlab_ci_and_token_present(self, gitlab_env):
+        detector = GitLabCIDetector(context=CredentialContext())
+        assert detector.detect() is True
+
+    def test_not_detected_when_unset(self):
+        with mock.patch.dict("os.environ", {}, clear=True):
+            detector = GitLabCIDetector(context=CredentialContext())
+            assert detector.detect() is False
+
+    def test_not_detected_without_gitlab_ci_flag(self, gitlab_env):
+        del gitlab_env["GITLAB_CI"]
+        with mock.patch.dict("os.environ", gitlab_env, clear=True):
+            detector = GitLabCIDetector(context=CredentialContext())
+            assert detector.detect() is False
+
+    def test_not_detected_when_gitlab_ci_not_true(self, gitlab_env):
+        gitlab_env["GITLAB_CI"] = "false"
+        with mock.patch.dict("os.environ", gitlab_env, clear=True):
+            detector = GitLabCIDetector(context=CredentialContext())
+            assert detector.detect() is False
+
+    def test_not_detected_without_any_token(self, gitlab_env):
+        del gitlab_env["CLOUDSMITH_OIDC_TOKEN"]
+        with mock.patch.dict("os.environ", gitlab_env, clear=True):
+            detector = GitLabCIDetector(context=CredentialContext())
+            assert detector.detect() is False
+
+    def test_detects_with_legacy_ci_job_jwt_v2(self, gitlab_env):
+        del gitlab_env["CLOUDSMITH_OIDC_TOKEN"]
+        gitlab_env["CI_JOB_JWT_V2"] = "legacy-jwt"
+        with mock.patch.dict("os.environ", gitlab_env, clear=True):
+            detector = GitLabCIDetector(context=CredentialContext())
+            assert detector.detect() is True
+
+
+class TestGetToken:
+    def test_returns_preferred_token(self, gitlab_env):
+        detector = GitLabCIDetector(context=CredentialContext())
+        assert detector.get_token() == "the-jwt"
+
+    def test_prefers_cloudsmith_token_over_legacy(self, gitlab_env):
+        gitlab_env["CI_JOB_JWT_V2"] = "legacy-jwt"
+        with mock.patch.dict("os.environ", gitlab_env, clear=True):
+            detector = GitLabCIDetector(context=CredentialContext())
+            assert detector.get_token() == "the-jwt"
+
+    def test_falls_back_to_legacy_token(self, gitlab_env):
+        del gitlab_env["CLOUDSMITH_OIDC_TOKEN"]
+        gitlab_env["CI_JOB_JWT_V2"] = "legacy-jwt"
+        with mock.patch.dict("os.environ", gitlab_env, clear=True):
+            detector = GitLabCIDetector(context=CredentialContext())
+            assert detector.get_token() == "legacy-jwt"
+
+    def test_raises_when_no_token(self, gitlab_env):
+        del gitlab_env["CLOUDSMITH_OIDC_TOKEN"]
+        with mock.patch.dict("os.environ", gitlab_env, clear=True):
+            detector = GitLabCIDetector(context=CredentialContext())
+            with pytest.raises(ValueError):
+                detector.get_token()
+
+
+class TestIntegration:
+    def test_detect_environment_selects_gitlab_ci(self, gitlab_env):
+        detector = detect_environment(CredentialContext())
+        assert isinstance(detector, GitLabCIDetector)