Documentation
Book a demo

Integrations

Azure DevOps

Effortlessly integrate Cloudsmith with Azure DevOps to securely manage artifacts and automate deployments.

Introduction

Cloudsmith integrates directly with Azure DevOps using OpenID Connect (OIDC) — enabling secure, short-lived authentication without Azure Entra app registrations or long-lived credentials.
This guide explains how to configure Cloudsmith and Azure DevOps to authenticate pipelines and access Cloudsmith repositories seamlessly.

What You’ll Need

Before getting started, ensure you have:

  • An Azure DevOps organization and project with permissions to create pipelines.
  • A Cloudsmith workspace (organization) with access to manage service accounts and OIDC providers.
  • The Cloudsmith CLI Setup & Authenticate Azure DevOps extension installed.

Integration Features

  • Native OIDC Authentication – Azure DevOps issues short-lived tokens that the Cloudsmith CLI exchanges for short-lived Cloudsmith credentials.
  • Standalone CLI Setup – Installs the standalone Cloudsmith CLI binary and adds it to PATH; no Python or pip required on the agent.
  • Cross-Platform – Works on Linux, Windows, and macOS agents.
  • No Entra App Needed – Uses Azure DevOps’ native OIDC provider directly.

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

Step 1: Create an OIDC Provider in Cloudsmith

  1. In your Cloudsmith workspace, go to Settings → Authentication → OpenID Connect → Create Provider.

  2. Fill in the following details:

    • Provider Name: azure-devops

    • OIDC Provider URL:

      https://vstoken.dev.azure.com/<ORG_GUID>

      Replace <ORG_GUID> with your Azure DevOps organization ID (GUID).
      You can find it at
      https://app.vssps.visualstudio.com/_apis/accounts — look for the "AccountId" value that corresponds to your organization, for example:

      json
      {"AccountId": "12345678-abcd-4321-ef00-987654321000", "AccountName": "acme-corp"}

    • Recommended Token Claims: Set the aud claim to api://AzureADTokenExchange, the audience Azure DevOps uses for its OIDC tokens. This audience is fixed by Azure DevOps and is not configurable. We also strongly recommend including at least one scoping claim to control which Azure DevOps pipelines can authenticate with Cloudsmith. Claims help ensure that only specific projects or repositories within your organization can access a given Cloudsmith service account.

      Example:

      json
      {
  "aud": "api://AzureADTokenExchange",
  "sub": "p://acme-corp/cloudsmith-integration/.*",
  "prj_id": "a1b2c3d4-e5f6-7890-abcd-1234567890ef"
}

      Explanation:

      • aud — The audience of the Azure DevOps OIDC token, api://AzureADTokenExchange.
      • sub — Identifies the Azure DevOps organization and project.
        In this example, only pipelines in the cloudsmith-integration project of the acme-corp organization can authenticate.
        The .* wildcard allows all pipelines in that project to use the same Cloudsmith OIDC mapping.
      • prj_id — The Azure DevOps project ID (GUID). You can use this for tighter scoping if needed.

      You can view your Azure DevOps organization and project IDs using:
      https://app.vssps.visualstudio.com/_apis/accounts — this lists your organization GUIDs and other identifiers that also appear as claims in your Azure DevOps OIDC tokens.

      Wildcard usage

      Wildcards are only supported at the end of a claim value.
      For example: p://acme-corp/cloudsmith-integration/*

    • Service Accounts: Select the Cloudsmith service account(s) that this provider will authenticate (for example, ado-builds-service).

  3. Click Create Settings to save.

Token exchange

The Cloudsmith CLI exchanges the Azure DevOps token for a short-lived Cloudsmith credential on its first authenticated command in each pipeline run.

Step 2: Add the Cloudsmith Task to Your Azure Pipeline

Install the Cloudsmith CLI Setup & Authenticate Azure DevOps extension.
It installs the standalone Cloudsmith CLI, adds it to PATH, and configures authentication for the rest of the job.

Example pipeline using native Azure DevOps OIDC:

yaml
# azure-pipelines.yml
trigger:
- main

pool:
  vmImage: 'ubuntu-latest'

variables:
  # ---- Cloudsmith settings ----
  CS_WORKSPACE: 'example-workspace'
  CS_SERVICE_SLUG: 'ado_build_service'   # Cloudsmith service account slug

steps:
- checkout: self

# Install the Cloudsmith CLI and configure OIDC (no Entra setup required)
- task: CloudsmithCliSetupAndAuthenticate@2
  displayName: "Set up Cloudsmith CLI"
  inputs:
    authMethod: 'oidc'
    oidcNamespace: '$(CS_WORKSPACE)'
    oidcServiceSlug: '$(CS_SERVICE_SLUG)'
    verifyAuth: true
  env:
    SYSTEM_ACCESSTOKEN: $(System.AccessToken)

# Any later step that runs an authenticated 'cloudsmith' command
- script: cloudsmith whoami
  displayName: "Verify Cloudsmith authentication"
  env:
    SYSTEM_ACCESSTOKEN: $(System.AccessToken)

SYSTEM_ACCESSTOKEN mapping

Map SYSTEM_ACCESSTOKEN on the setup task and every later step that runs an authenticated cloudsmith command. System.AccessToken is the short-lived, job-scoped OAuth token created by Azure DevOps; it is not a personal access token (PAT) that you create or store. Azure Pipelines does not automatically expose secret variables to task processes, and the CLI exchanges the OIDC token on its first authenticated command.

To pin a specific CLI version, set cliVersion: '1.20.1' in the task inputs. The default installs the latest release.

Step 3: Verify CLI Installation and Authentication

Save and run your pipeline to complete the setup.
With verifyAuth: true, the task validates the setup during installation by running:

bash
cloudsmith whoami

The command exits with code 0 when authenticated and 1 when anonymous. You can check the pipeline logs to confirm successful authentication.

Step 4: Start Using the Cloudsmith CLI Seamlessly in Your Pipeline

The following example demonstrates how to use the Cloudsmith CLI extension with OIDC authentication to push a package to Cloudsmith directly from an Azure DevOps pipeline:

yaml
trigger:
  branches:
    include:
      - main  # Trigger pipeline on changes to the main branch

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: CloudsmithCliSetupAndAuthenticate@2
    displayName: "Set up Cloudsmith CLI"
    inputs:
      authMethod: 'oidc'
      oidcNamespace: 'example-workspace'
      oidcServiceSlug: 'ado_build_service'
      cliVersion: '1.20.1'
    env:
      SYSTEM_ACCESSTOKEN: $(System.AccessToken)

  # Example task: push a raw package to Cloudsmith
  - script: cloudsmith push raw example-workspace/backend-app ./dist/my-package.zip
    displayName: "Push package to Cloudsmith"
    env:
      SYSTEM_ACCESSTOKEN: $(System.AccessToken)

Once authenticated, you can perform any Cloudsmith CLI operation — such as pushing, pulling, or managing packages — directly within your Azure DevOps pipeline.

Pipeline steps

Ensure that all pipeline steps that call the Cloudsmith CLI run on the same pipeline runner as the Cloudsmith authentication task.

Best Practices

  • Use OIDC: Use OIDC authentication instead of API keys for enhanced security.
  • Use Secure Variables: Store sensitive values (e.g., CLOUDSMITH_API_KEY, workspace/repo names) as Azure DevOps secrets rather than hard-coding them in YAML.
  • Use Latest CLI Versions: Keep the Cloudsmith CLI updated to leverage the latest features and security patches. If specific versions are required, specify them explicitly in your configuration.

Troubleshooting

  • Authentication Issues:
    • Ensure all authentication variables are correctly set and valid for either API Key or OIDC.
    • Verify that the correct service account is selected in Cloudsmith for the OIDC provider.
  • Permission Errors: Verify that the Azure DevOps agent has permission to download and install the CLI (for self-hosted agents).
  • PATH Issues with Cloudsmith CLI: Ensure you’re using the same runner for all steps, as switching runners may lose CLI installation and configuration.
  • OIDC authentication failures: Ensure the Provider URL exactly matches https://vstoken.dev.azure.com/<ORG_GUID> for your organization. If you added sub or other claims, confirm they match the token your pipeline issues.
  • Missing SYSTEM_ACCESSTOKEN: If an authenticated cloudsmith command fails with OIDC, confirm that SYSTEM_ACCESSTOKEN: $(System.AccessToken) is mapped in the env of that step, not just the setup task.