Documentation
Open Cloudsmith

Integrations

Integrating Cloudsmith with GitHub Actions

Use the Cloudsmith CLI in your workflows via the official Cloudsmith CLI Install Action. This action can:

  • Authenticate with Cloudsmith using either an API key or OIDC (recommended for CI)
  • Install the Cloudsmith CLI (zipapp download or optional pip install)
  • Optionally only perform OIDC auth (skip CLI install) for lightweight API interactions

Cloudsmith CLI Install Action

Official GitHub Action to authenticate and install the Cloudsmith CLI

View on GitHub

Action Overview

This GitHub Action installs the Cloudsmith CLI and pre-authenticates it using OIDC or API Key.

OIDC Authentication (Recommended)

Add the id-token: write permission so the action can request an identity token. Cloudsmith exchanges this for a short-lived JWT which is exported as CLOUDSMITH_API_KEY.

yaml
permissions:
  id-token: write
  contents: read
steps:
  - uses: actions/checkout@v4
  - name: Authenticate & Install Cloudsmith CLI (OIDC)
    uses: cloudsmith-io/cloudsmith-cli-action@v1
    with:
      oidc-namespace: your-oidc-namespace
      oidc-service-slug: your-service-account-slug

OIDC Permissions & Token

Ensure permissions: id-token: write is present. The obtained JWT is automatically exported as CLOUDSMITH_API_KEY environment variable.

OIDC Authentication Only (Skip CLI Install)

Use when you only need the token for API calls:

yaml
steps:
  - uses: cloudsmith-io/cloudsmith-cli-action@v1
    with:
      oidc-namespace: your-oidc-namespace
      oidc-service-slug: your-service-account-slug
      oidc-auth-only: 'true'
  - name: Validate token
    run: curl -H "X-Api-Key: $CLOUDSMITH_API_KEY" https://api.cloudsmith.io/v1/user/self/

API Key Authentication

Use for quick tests or legacy setups when OIDC isn’t available.

yaml
steps:
  - uses: actions/checkout@v4
  - name: Install Cloudsmith CLI (API Key)
    uses: cloudsmith-io/cloudsmith-cli-action@v1
    with:
      api-key: ${{ secrets.CLOUDSMITH_API_KEY }}

Action Output

When OIDC is used the action:

  • Exports the token as CLOUDSMITH_API_KEY (env var)
  • Sets an output oidc-token

Installing the CLI

By default the action downloads the latest Cloudsmith CLI zipapp release. You can instead install via pip.

yaml
with:
  oidc-namespace: your-oidc-namespace
  oidc-service-slug: your-service-account-slug
  pip-install: 'true'
  cli-version: 1.3.0

The CLI binary (zipapp) is placed at the executable-path (defaults to bin/cloudsmith) and added to PATH. On Windows, a cloudsmith.bat wrapper is created.

Example: Publish a Python Package

yaml
name: Publish Python Package
on:
  push:
    branches: [ main ]
permissions:
  id-token: write
  contents: read
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - name: Build distribution
        run: |
          python -m pip install build
          python -m build
      - name: Install Cloudsmith CLI (OIDC)
        uses: cloudsmith-io/cloudsmith-cli-action@v1
        with:
          oidc-namespace: your-oidc-namespace
          oidc-service-slug: your-service-account-slug
      - name: Push to Cloudsmith
        run: cloudsmith push python your-namespace/your-repository dist/*.tar.gz

Secrets and Variables Setup

  1. In your GitHub repository go to Settings → Secrets and variables → Actions.
  2. Add secret CLOUDSMITH_API_KEY if using API key auth.
  3. For OIDC create a Cloudsmith service account and note its namespace and slug.
  4. Ensure workflow permissions: id-token: write.

Refer to Cloudsmith docs for Service Accounts and OIDC.

Supported Package Formats

As this action directly uses the Cloudsmith CLI, it supports all formats available in the CLI:

Support

If you need help, open an issue on the action's GitHub repository or visit support.cloudsmith.com.

See Also