Integrations

Integrating Cloudsmith with GitHub Actions

Use the Cloudsmith CLI in your workflows via the official Cloudsmith CLI Setup Action. The action:

• Installs the standalone Cloudsmith CLI and adds it to PATH (no Python or Node.js required on the runner)
• Configures authentication with Cloudsmith using either OIDC (recommended for CI) or an API key
• Works on Linux, macOS, and Windows runners, on x86-64 plus Linux and macOS ARM64

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

OIDC Authentication (Recommended)

OIDC is the recommended option for CI/CD because it uses short-lived credentials instead of a stored API key. Before using this example, configure a Cloudsmith service account and an OIDC provider by following the Cloudsmith OIDC documentation.

Add the id-token: write permission so the workflow can request an identity token:

permissions:
  id-token: write
  contents: read

steps:
  - uses: cloudsmith-io/cloudsmith-cli-action@v3
    with:
      oidc-namespace: 'your-workspace'
      oidc-service-slug: 'your-service-account-slug'

  - run: cloudsmith whoami

OIDC Permissions

The workflow or job must grant id-token: write. Without this permission, GitHub cannot issue the OIDC token used to authenticate with Cloudsmith.

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

API Key Authentication

Use an API key for workflows that cannot use OIDC. Store the API key as a GitHub Actions secret and pass it to the action. For automated workflows, use a Cloudsmith service account rather than a personal API key.

steps:
  - uses: cloudsmith-io/cloudsmith-cli-action@v3
    with:
      api-key: ${{ secrets.CLOUDSMITH_API_KEY }}

  - run: cloudsmith whoami

The action masks the key and exports it as CLOUDSMITH_API_KEY for later steps.

Configuration

An authentication method is required: Provide api-key, or provide both oidc-namespace and oidc-service-slug.

The action also accepts api-host, api-proxy, api-ssl-verify, and api-user-agent inputs, which are exported as the corresponding CLOUDSMITH_* environment variables for later steps. Note that api-ssl-verify maps inversely to CLOUDSMITH_WITHOUT_API_SSL_VERIFY: api-ssl-verify: true exports CLOUDSMITH_WITHOUT_API_SSL_VERIFY=false, and api-ssl-verify: false exports CLOUDSMITH_WITHOUT_API_SSL_VERIFY=true. See the action repository for the full reference.

Outputs

Access an output through the action step's id:

steps:
  - name: Set up Cloudsmith CLI
    id: cloudsmith
    uses: cloudsmith-io/cloudsmith-cli-action@v3
    with:
      api-key: ${{ secrets.CLOUDSMITH_API_KEY }}

  - run: echo "Installed Cloudsmith CLI ${{ steps.cloudsmith.outputs.cli-version }}"

Example: Publish a Python Package

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: Set up Cloudsmith CLI (OIDC)
        uses: cloudsmith-io/cloudsmith-cli-action@v3
        with:
          oidc-namespace: 'your-workspace'
          oidc-service-slug: 'your-service-account-slug'
      - name: Push to Cloudsmith
        run: cloudsmith push python your-workspace/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:

• Cloudsmith Supported Formats
• Cloudsmith CLI Features

Support

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

See Also

• Action Repository
• Cloudsmith CLI
• OIDC Docs
• Service Accounts
• Formats

Updated yesterday