Setup GitHub Actions to authenticate to Cloudsmith using OIDC

How does OIDC work with Github Actions and Cloudsmith?

The following diagram gives an overview of how GitHub's OIDC provider integrates with your workflows and Cloudsmith:

OIDC flow overview

1. Request token: GitHub Actions Worker initiates the workflow by requesting a token from the GitHub OIDC service to authenticate with Cloudsmith.
2. Return token: GitHub OIDC service receives the token request. After verification and validation, it generates a JWT token. The GitHub OIDC service and the GitHub Actions Worker have implicit trust, allowing for this token exchange.
3. Present token: GitHub Actions Worker presents a JWT token to Cloudsmith for access to resources.
4. Verify token: Cloudsmith verifies the JWT token with the GitHub OIDC service to ensure its authenticity and validity. This step includes verifying claims.
5. Return new token: Upon successful validation, Cloudsmith issues a short-lived access token to the GitHub Actions Worker, granting access to Cloudsmith's resources for around 90 mins to cover the duration of the job.

Step-by-Step Guide

Follow the steps below for the Cloudsmith and GitHub Actions OIDC Setup:

1. Create a Service Account in Cloudsmith and set Access Controls

1. Service accounts are a specific type of account that allows you to create a Cloudsmith API Key not tied to a specific user.
2. Navigate to the Services section on your Cloudsmith workspace's accounts page and click "Create Service".
3. In the form, give your Service a name and optionally add a description and choose any teams in your workspace that you wish to add the service to.
4. Configure the repository access controls to allow the Service Account to push packages to Cloudsmith.

2. Configure GitHub OIDC in Cloudsmith

📘

Role requirement

Manager or Owner role required in your Cloudsmith workspace to configure OIDC Provider Settings.

1. Navigate to the OIDC Provider Settings at: https://app.cloudsmith.com/{WORKSPACE}/settings/authentication/openid

2. Click "Create" to open the Edit Provider Settings form.

3. Fill in the OIDC form:

   • Provider Name: set a unique name for the provider.
   • Provider URL: This URL must precisely match the iss (issuer) claim from the OIDC token generated by your GitHub environment:
     • Standard GitHub.com: The URL is typically https://token.actions.githubusercontent.com.
     • GitHub Enterprise Cloud: The URL will include your enterprise name, like https://token.actions.githubusercontent.com/YOUR_ENTERPRISE_NAME.
   • Required OpenID Token Claims: To validate the token, the cloud provider checks if the OIDC token's subject and other claims are a match for the conditions that were preconfigured on the cloud role's OIDC trust definition.
   • Service Accounts: Select the service accounts that can be authenticated with this provider and claim combination.

   📘

   Claims

   We strongly encourage you to set at least one claim. Without claims, any GitHub Action that knows the service account slug could gain access. In the example, we use repository_owner.

3. Update your GitHub Actions for OIDC

Cloudsmith provides a native GitHub action integration, that avoids a manual exchange of tokens.

1. Add permissions: In your GitHub Actions YAML file, add the permissions block to allow the workflow to request an OIDC token.

permissions:
  id-token: write # Required for requesting the JWT
  contents: read  # Required for actions/checkout

2. Authenticate using the Cloudsmith Action: Add the following step to your job. It will handle the entire OIDC token exchange process automatically and configure the Cloudsmith CLI for any subsequent steps.

- name: Authenticate with Cloudsmith via OIDC
  uses: cloudsmith-io/[email protected]
  with:
    oidc-namespace: 'your-workspace' # Your Cloudsmith workspace
    oidc-service-slug: 'your-service-account-slug' # Your Cloudsmith service account slug
    oidc-auth-only: 'true' # Ensures the action only performs authentication

The action fetches the OIDC token from GitHub, exchanges it for a Cloudsmith token, and sets the CLOUDSMITH_API_KEY environment variable for the rest of the job. Finally, add any extra step for your workflow and trigger a build in GitHub Actions.

Example GitHub Actions Workflow

Below is a full example of pushing a package to Cloudsmith in GitHub Actions using the modern OIDC authentication method.

name: Push a Debian package to Cloudsmith with OIDC
on:
  push:
    branches: [ main ]

permissions:
  id-token: write # Required to request the OIDC token from GitHub
  contents: read  # Required for actions/checkout to read the repository

jobs:
  push:
    runs-on: ubuntu-latest
    name: Push a Debian package to Cloudsmith using OIDC
    steps:
      - name: Check out code
        uses: actions/checkout@v4

      # This step handles the entire OIDC authentication flow automatically.
      # It gets a token from GitHub and exchanges it for a Cloudsmith token.
      - name: Authenticate with Cloudsmith via OIDC
        uses: cloudsmith-io/[email protected]
        with:
          oidc-namespace: 'WORKSPACE'             # Replace with your Cloudsmith workspace
          oidc-service-slug: 'SERVICE_ACCOUNT_SLUG' # Replace with your service account slug
          oidc-auth-only: 'false'
      - name: Push package to Cloudsmith
        run: |
          cloudsmith push deb WORKSPACE/REPOSITORY/DISTRO/VERSION PACKAGE_NAME-PACKAGE_VERSION.PACKAGE_ARCH.deb