Integrations

Integrating CircleCI

Cloudsmith provides first-class support for CircleCI with our official orb. Using the orb, users can easily integrate publishing to Cloudsmith with their existing CircleCI workflows.

Full reference documentation for the orb can be found on the CircleCI website. This documentation is automatically generated from the orb itself and so is guaranteed to always be up to date with the latest release of the orb.

No Code Uploading

The Cloudsmith CLI gives you full control when connecting to any CI/CD process, allowing you to upload any of our support formats or query your repositories. Just configure your API Key, install the CLI, and you'll be all set.

Orb usage example

To use the orb you must first ensure you are using Circle version 2.1. At the top of your .circleci/config.yml file you should add:

version: 2.1

And then include the orb:

orbs:
  cloudsmith: cloudsmith/cloudsmith@3.0.0

Note that you can check the releases page on GitHub for our orb, or the orb page on CircleCI itself to find the latest version to use.

The orb installs the standalone Cloudsmith CLI binary with SHA-256 download verification and adds it to PATH; it does not require Python, pip, or jq on the executor image.

Migrating from an earlier version of the orb? See the migration guide.

OIDC Authentication (recommended)

The recommended approach is to install the CLI, configure OIDC, and invoke the CLI directly in your run steps. This uses short-lived tokens and avoids storing long-lived API keys:

version: 2.1

orbs:
  cloudsmith: cloudsmith/cloudsmith@3.0.0

workflows:
  cloudsmith_oidc_publish:
    jobs:
      - publish:
          context: my-context

jobs:
  publish:
    executor: cloudsmith/default
    steps:
      - checkout
      - cloudsmith/install-cli
      - cloudsmith/configure-oidc:
          organization: my-org
          service-account: my-service-account
      - run:
          name: Publish package
          command: cloudsmith push raw my-org/my-repo dist/app.tar.gz

The configure-oidc command exports the service account context (CLOUDSMITH_ORG and CLOUDSMITH_SERVICE_SLUG) needed by the CLI. The CLI exchanges a CircleCI OIDC token on its first authenticated command, and the Cloudsmith access token is not exposed by the orb. Set verify-auth: true on configure-oidc to run cloudsmith whoami during setup and fail early if authentication is not configured correctly.

CircleCI context required

The job must use at least one CircleCI context. Without a context, CircleCI does not issue the OIDC token used to authenticate with Cloudsmith.

To pin a specific CLI version, set cli-version: '1.20.1' on install-cli. The default installs the latest release.

API Key Authentication

If OIDC is not available in your environment, you can authenticate with a static API key. Add an environment variable named CLOUDSMITH_API_KEY in your CircleCI project settings:

Then use ensure-api-key to validate the key is set before running CLI commands:

version: 2.1

orbs:
  cloudsmith: cloudsmith/cloudsmith@3.0.0

workflows:
  cloudsmith_publish:
    jobs:
      - publish

jobs:
  publish:
    executor: cloudsmith/default
    steps:
      - checkout
      - cloudsmith/ensure-api-key
      - cloudsmith/install-cli
      - run:
          name: Publish package
          command: cloudsmith push raw my-org/my-repo dist/app.tar.gz

Note

The cloudsmith/default executor uses the cimg/base convenience image. If you need a different base image, you can specify your own executor and the orb commands will work on any Linux or macOS executor that provides bash; curl or GNU wget with --https-only support; tar; gzip; and one of sha256sum, shasum, or openssl.

Support

As always, if you have any questions about integration or would like some general advice, please contact support.

Updated 1 minute ago