Integrations

Integrating CircleCI

How to integrate CircleCI with Cloudsmith

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@2.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.

OIDC Authentication (recommended)

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

version: 2.1

orbs:
  cloudsmith: cloudsmith/cloudsmith@2.0.0

workflows:
  cloudsmith_oidc_publish:
    jobs:
      - publish

jobs:
  publish:
    executor: cloudsmith/default
    steps:
      - checkout
      - cloudsmith/authenticate-with-oidc:
          organization: my-org
          service-account: my-service-account
      - cloudsmith/install-cli
      - run:
          name: Build and publish Python package
          command: |
            pip install build
            python -m build --wheel
            cloudsmith push python my-org/my-repo dist/*.whl

The authenticate-with-oidc command exchanges a CircleCI OIDC token for a short-lived Cloudsmith API token, exported as CLOUDSMITH_API_KEY. Ensure OIDC is enabled in your CircleCI project settings (Project Settings → Advanced → Enable OpenID Connect Tokens).

If you only need the API token and don't need to install the CLI, you can use authenticate-with-oidc on its own:

jobs:
  authenticate:
    executor: cloudsmith/default
    steps:
      - checkout
      - cloudsmith/authenticate-with-oidc:
          organization: my-org
          service-account: my-service-account
      - run:
          name: Call Cloudsmith API
          command: |
            curl -H "X-Api-Key: $CLOUDSMITH_API_KEY" \
              https://api.cloudsmith.io/user/self/

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@2.0.0

workflows:
  cloudsmith_publish:
    jobs:
      - publish

jobs:
  publish:
    executor: cloudsmith/default
    steps:
      - checkout
      - cloudsmith/ensure-api-key
      - cloudsmith/install-cli
      - run:
          name: Build and publish Python package
          command: |
            pip install build
            python -m build --wheel
            cloudsmith push python my-org/my-repo dist/*.whl

Note

The cloudsmith/default executor uses the cimg/python convenience image. If you need a different base image, you can specify your own executor and the orb commands will work in any environment that has the required dependencies (Python, curl, jq).

Support

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

Updated 2 days ago