--- title: "CircleCI Integration - Publish Packages with Cloudsmith" description: "Connect CircleCI to Cloudsmith using the official orb. Publish packages across 30+ formats, enforce security policies, and get full traceability on every artifact your pipelines produce." canonical_url: "https://cloudsmith.com/product/integrations/circle-ci" last_updated: "2026-05-07T09:33:44Z" --- # CircleCI Integration - Publish Packages with Cloudsmith ## Publish packages to Cloudsmith directly from your **CircleCI** pipeline Cloudsmith provides first-class support for CircleCI through its official orb, giving your pipelines a secure, fully managed artifact repository without manual tooling or fragile scripts. Connect your CircleCI workflows to Cloudsmith in minutes and get complete control over every package you publish. Product / Integrations ## CircleCI Integration CircleCI is a cloud-based continuous integration and delivery (CI/CD) platform that helps software teams automate the build, test, and deployment processes. Using our integration enables users to effortlessly publish to Cloudsmith as part of their existing CircleCI workflows. ## How we support **CircleCI** Cloudsmith integrates directly into your CircleCI pipelines via the official orb, giving your team a secure, multi-format artifact repository that works across every workflow you already run. [Read our CircleCI documentation](https://docs.cloudsmith.com/integrations/integrating-with-circleci) ### Official CircleCI orb The Cloudsmith orb gives you reusable, versioned pipeline steps for authentication, CLI installation, and package publishing. Drop it into any config.yml with a single line and start publishing immediately. ### 30+ package formats supported Publish Python, Debian, RPM, npm, Maven, Docker, Helm, and many more formats directly from your CircleCI jobs. One registry handles every artifact type your pipelines produce. ### Secure API key authentication Store your Cloudsmith API key as a CircleCI environment variable and the orb handles the rest. Credentials are never exposed in logs or config files, keeping your supply chain secure. ### Full CLI flexibility For workflows that go beyond the orb's standard commands, use the Cloudsmith CLI directly. Mix orb commands with raw CLI calls to handle any custom publishing or querying requirement. ### Full audit trail and analytics Every package published via CircleCI is logged with client and audit data in Cloudsmith. Track which pipeline, job, and commit produced each artifact for complete traceability across your organisation. ## Why teams integrate Cloudsmith with **CircleCI** CircleCI handles your build and test pipeline well, but without a dedicated artifact registry your published packages are scattered, insecure, and hard to trace. Cloudsmith closes that gap. | Without Cloudsmith | With Cloudsmith | | --- | --- | | CircleCI's native artifact storage has a 30-day maximum retention limit and no package-manager-compatible API. Teams end up scripting ad-hoc uploads to S3, public registries, or self-hosted tools, creating fragile pipelines that break on rotation. | Cloudsmith gives every CircleCI pipeline a permanent, package-manager-native repository. Artifacts are retained indefinitely, indexed for audit, and instantly consumable by the same package managers used in development and production. | | Publishing to multiple format-specific registries from CircleCI means maintaining separate credentials, upload scripts, and tooling for each one. A single pipeline touching npm, Debian, and Docker requires three separate integrations. | One Cloudsmith orb step handles every format your CircleCI jobs produce. A single API key, a single repository, and a single audit trail cover npm, Debian, RPM, Docker, Helm, and 25+ more formats with no extra scripts. | | Packages published from CircleCI with no policy layer reach consumers unscanned. Vulnerabilities in build outputs only surface after deployment, and there is no automated gate to quarantine a bad release before it propagates. | Cloudsmith scans every package on upload and can quarantine or block distribution based on OPA Rego policies. Security gates run automatically as part of the CircleCI pipeline, stopping vulnerable artifacts before they reach downstream consumers. | ## Frequently asked questions ### How do I add the Cloudsmith orb to my CircleCI config? Add `version: 2.1` to the top of your .circleci/config.yml file, then declare the orb with `cloudsmith: cloudsmith/cloudsmith@`. From there you can use the orb's commands directly in your job steps to install the CLI, validate your API key, and publish packages. ### How is authentication handled between CircleCI and Cloudsmith? You store your Cloudsmith API key as a CircleCI environment variable named CLOUDSMITH_API_KEY in your project settings. The orb's `cloudsmith/ensure-api-key` command checks for this variable at runtime so credentials are never hardcoded or exposed in build logs. ### Which package formats can I publish via the CircleCI orb? The Cloudsmith orb supports all formats Cloudsmith handles, including Python, Debian, RPM, npm, Maven, Docker, Helm, NuGet, Ruby Gems, and 20+ more. You specify the format with the `package-format` parameter in the `cloudsmith/publish` step. ### What if the orb doesn't cover my exact workflow? For custom requirements, you can mix orb commands with direct Cloudsmith CLI calls. Use the orb to handle installation and authentication, then invoke the CLI directly for any advanced operations like querying repositories or pushing packages with non-standard options. ### Does Cloudsmith retain packages published from CircleCI indefinitely? Yes. Unlike CircleCI's native artifact storage which has a 30-day maximum retention, packages stored in Cloudsmith are retained for as long as you need them. Retention and deletion policies can be configured per repository in Cloudsmith. ### Can I run security scanning on packages published from CircleCI? Yes. Cloudsmith automatically scans packages for vulnerabilities on upload. You can configure OPA Rego policies to quarantine or block distribution of packages that fail your security criteria, giving you an automated gate inside your CircleCI pipeline. ### Can I publish to multiple Cloudsmith repositories from the same CircleCI pipeline? Yes. You can include multiple `cloudsmith/publish` steps in a single job, each targeting a different repository. This is useful for workflows that publish to a staging repository on every merge and a production repository on tagged releases. ### How do I track which CircleCI build produced a given package? Cloudsmith logs full client and audit metadata for every upload, including timestamps and authentication context. This gives you a traceable record linking each package version back to the pipeline that produced it. ### Is there a CircleCI version requirement for using the orb? Yes, you need to be using CircleCI version 2.1 or later. This is declared at the top of your config.yml file with `version: 2.1`. All modern CircleCI accounts support this by default. ### Where can I find the latest version of the Cloudsmith orb? The latest release is always available on the CircleCI Developer Hub under cloudsmith/cloudsmith. The reference documentation there is generated directly from the orb itself and reflects the most current commands, parameters, and examples.