feat!: install the standalone CLI and authenticate via native OIDC

[BartoszBlizniak]

Description

This PR introduces version 3 of the Cloudsmith CircleCI orb. It replaces the Python-based installation with the standalone Cloudsmith CLI and moves OIDC authentication into the CLI, reducing executor dependencies and keeping credential exchange within the supported client.

Area	What changes
Installation	Installs a SHA-256-verified standalone CLI binary on Linux and macOS
Authentication	Supports API keys and CLI-native CircleCI OIDC authentication
Configuration	Adds explicit CLI version selection and versioned installation paths
Publishing	Uses cloudsmith push directly instead of an orb wrapper command
Executor	Moves the default executor from cimg/python to the smaller cimg/base image
Documentation	Aligns the README with the other Cloudsmith CI integrations and adds a complete v2-to-v3 migration guide

Note

OIDC remains the recommended authentication method. Jobs using OIDC must use at least one CircleCI context so CircleCI issues an identity token.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring
• Other (please describe)

Breaking Changes

Important

Version 3 removes commands and parameters that depended on Python or exposed a Cloudsmith API token. Existing version 2 configurations must be updated before changing the orb version.

Version 2	Version 3 migration
Python zipapp or pip-install	Remove Python-specific setup. install-cli now installs the standalone binary.
authenticate-with-oidc	Replace with configure-oidc. The CLI performs the token exchange on first use.
OIDC exports CLOUDSMITH_API_KEY	No Cloudsmith API token is exported. Run authenticated operations through the CLI.
oidc-audience and oidc-auth-retry	Remove these parameters. Configure the audience in Cloudsmith; the CLI manages retries.
publish command	Run cloudsmith push directly after installation and authentication.
install-path points to a single binary location	Treat it as the root for versioned CLI installations.
Default executor uses cimg/python	The default executor now uses cimg/base; add Python only if other job steps require it.

Additional Notes

The orb has been packed and validated with the CircleCI CLI. Shell syntax and ShellCheck validation pass for all bundled scripts, and the generated orb matches the source configuration.

Tip

See the v2-to-v3 migration guide for command examples and parameter-level migration details.

[Copilot]

Pull request overview

Updates the CircleCI orb to v3 by switching from the Python-based Cloudsmith CLI install/auth flow to a standalone CLI binary with SHA-256 verification and CLI-native OIDC authentication, reducing executor dependencies and removing token export behavior.

Changes:

• Replace install-cli with a bundled installer that downloads/verifies a standalone Cloudsmith CLI binary and adds it to PATH via $BASH_ENV.
• Replace authenticate-with-oidc with configure-oidc, exporting only CLI context variables and relying on the CLI to perform OIDC token exchange on first authenticated use.
• Refresh docs/examples and CircleCI config to reflect v3 usage and add installer drift checking + integration test workflow.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/scripts/post-install.sh	Reads installer results, adds CLI to PATH, and writes optional ~/.cloudsmith/config.ini.
src/scripts/install.sh.version	Records the vendored installer “version” and checksum for drift checking.
src/scripts/install.sh	New standalone CLI installer: target detection, manifest fetch, SHA-256 verification, safe extraction, versioned install layout.
src/scripts/configure-oidc.sh	Exports CLI OIDC context variables for later steps; validates CircleCI token presence.
src/executors/default.yml	Switch default executor image from cimg/python to cimg/base.
src/examples/install-with-oidc.yml	New v3 example using install-cli + configure-oidc.
src/examples/install-with-api-key.yml	New v3 example using ensure-api-key + install-cli.
src/examples/command-publish.yml	Removes v2 example that used the orb publish wrapper command.
src/examples/cli-with-oidc.yml	Removes v2 OIDC example based on authenticate-with-oidc.
src/examples/authenticate-with-oidc.yml	Removes v2 example for token-exchange command.
src/commands/publish.yml	Removes deprecated v2 publish wrapper command.
src/commands/install-cli.yml	Reworks install to call bundled installer + post-install step; updates parameters and defaults.
src/commands/configure-oidc.yml	Adds new configure-oidc command with optional verify-auth step.
src/commands/authenticate-with-oidc.yml	Removes v2 OIDC token-exchange command that exported CLOUDSMITH_API_KEY.
src/@orb.yml	Updates orb description to reflect standalone CLI + direct CLI usage.
README.md	Major documentation refresh: v3 quickstart, configuration, and v2→v3 migration guide.
.circleci/test-deploy.yml	Adds/updates integration tests (install matrix, pinned version check, API key + OIDC flows) and publishing workflow.
.circleci/config.yml	Converts to setup workflow, adds ShellCheck + installer drift check, and continues into test/deploy pipeline.

---

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

[cloudsmith-iduffy]

😍