Introduction
IntroductionMigrate from CLI v1 to v2Authenticate without an API key (OIDC)Authenticate a pipeline with OIDCMigrate from the legacy GitHub Actions OIDC flowUse the CLI with Docker image
IntroductionChoose a value for build nameRecord builds from multiple repositoriesRecord builds for microservicesRecord builds for multistage buildRun under restricted networksDeal with shallow clones
Record sessions
IntroductionRequest and run a subset of testsSubset with the CloudBees Smart Tests CLIChoose a subset optimization targetObserve subset behaviorSmart subset optimization targetsZero Input SubsettingReplace static parallel suites with a dynamic parallel subsetUse groups to split subsetsCombine with rule-based test selectionCloudBees Smart Tests extension for VS code
IntroductionConvert test reports to JUnit formatEnsure record tests always runsManage complex test session layoutsUse 'flavors' to run the best tests for an environmentSeparate out test suitesAttach log files

Authenticate without an API key (OIDC)

2 minute read

Authentication between the CloudBees Smart Tests CLI and CloudBees Smart Tests API normally requires a static API key. As an alternative, CloudBees Smart Tests supports tokenless authentication using OpenID Connect (OIDC). Instead of a shared secret, the CI system issues a short-lived, signed OIDC id-token for each pipeline run, and CloudBees Smart Tests verifies it cryptographically. There is no key to rotate or leak.

A single generic OIDC flow authenticates every supported CI provider, including GitHub Actions, Jenkins, GitLab, and any other OpenID Connect issuer. The CI mints an id-token for the pipeline, CloudBees Smart Tests verifies it against that issuer, and matches the token’s sub claim against a Trusted OIDC subject that you register once in the web app.

To set up a pipeline, follow Authenticate a pipeline with OIDC. That page includes GitHub Actions, Jenkins, and other providers as separate worked examples.

GitHub Actions previously used a legacy flow that matched the repository claim and required a manual repository-to-workspace association by CloudBees Support. That path is still supported for backward compatibility but is deprecated. Existing GitHub Actions pipelines keep working during migration: CloudBees Smart Tests automatically falls back to the legacy repository-claim verification for a workspace that has not yet registered a matching Trusted OIDC subject. Refer to Migrate from the legacy GitHub Actions OIDC flow if you set EXPERIMENTAL_GITHUB_OIDC_TOKEN_AUTH today.

How OIDC verification works

Both paths rely on the same underlying mechanism.

An OIDC id-token is a signed JWT that the CI mints for a pipeline run. It carries three claims that matter here:

  • iss (issuer) - who minted the token, for example https://token.actions.githubusercontent.com (GitHub) or https://jenkins.example.com/oidc (Jenkins).

  • sub (subject) - the identity of the specific pipeline or job. CloudBees Smart Tests matches this against the value you registered as a Trusted OIDC subject. For GitHub Actions, the token’s raw sub is normalized to repo:OWNER/REPO before matching, so the registered value is the same regardless of branch or workflow.

  • aud (audience) - who the token is intended for. CloudBees Smart Tests expects https://app.cloudbees.io/smart-tests.

To verify a token, CloudBees Smart Tests needs the issuer’s public keys, published as a JSON Web Key Set (JWKS). A JWKS contains only public keys: it allows CloudBees Smart Tests to verify a signature but cannot be used to mint tokens.

The issuer signs each token with a private key, and CloudBees Smart Tests checks the signature with the matching public key from the issuer’s JWKS. This proves the token genuinely came from that issuer and was not tampered with, without any shared secret.

The /.well-known/openid-configuration and /.well-known/jwks paths are an OIDC Discovery convention: a standard location where any compliant issuer advertises its configuration and public keys.
Migrate from CLI v1 to v2
Authenticate a pipeline with OIDC