diff --git a/src/content/authentication/openid-connect.mdx b/src/content/authentication/openid-connect.mdx index 7e7f1031..d9d640a2 100644 --- a/src/content/authentication/openid-connect.mdx +++ b/src/content/authentication/openid-connect.mdx @@ -184,69 +184,40 @@ pipelines: #### CircleCI Example +Using the [Cloudsmith CircleCI orb](https://circleci.com/developer/orbs/orb/cloudsmith/cloudsmith), the `authenticate-with-oidc` command handles the token exchange automatically and exports the result as `CLOUDSMITH_API_KEY`: + ```yaml version: 2.1 -commands: - make_oidc_request: - steps: - - run: | - echo "Testing CircleCI OIDC." - jwt=$(curl -X POST -H "Content-Type: application/json" -d "{\"oidc_token\":\"$CIRCLE_OIDC_TOKEN_V2\", \"service_slug\":\"{SERVICE_SLUG}"}" https://api.cloudsmith.io/openid/{ACCOUNT}/ | jq -r '.token') - echo "OIDC token from Cloudsmith: $jwt" +orbs: + cloudsmith: cloudsmith/cloudsmith@2.0.0 -jobs: - build: - docker: - - image: cimg/base:current - steps: - - make_oidc_request - workflows: - test-workflow: + cloudsmith_oidc_publish: jobs: - - build: - context: - - circle-oidc-test -``` - -If successful, this will give a JWT token to be used as an API key. - -If unsuccessful, you will receive an error message that is intentionally quite generic. This is by design so that we do not leak any information (such as whether OIDC is configured, which claim failed, whether a service account is associated with the provider, etc.). - -Additionally, as of version `1.0.6` of the Cloudsmith orb, you can use the `authenticate-with-oidc` command to perform this step automatically. - -```yaml -version: 2.1 - -orbs: - cloudsmith: cloudsmith/cloudsmith@1.0.6 - python: circleci/python@2.1.1 + - publish jobs: publish: - executor: python/default + executor: cloudsmith/default steps: - checkout - cloudsmith/authenticate-with-oidc: - organization: - service-account: - - cloudsmith/ensure-api-key + organization: my-org + service-account: my-service-account - cloudsmith/install-cli - run: - name: Build Python package - command: python setup.py sdist - - cloudsmith/publish: - cloudsmith-repository: / - package-path: dist/*.tar.gz - package-format: python - -workflows: - cloudsmith_publish: - jobs: - - publish + name: Build and publish Python package + command: | + pip install build + python -m build --wheel + cloudsmith push python my-org/my-repo dist/*.whl ``` +Ensure OIDC is enabled in your CircleCI project settings (Project Settings → Advanced → Enable OpenID Connect Tokens). + +If successful, `CLOUDSMITH_API_KEY` will be set for all subsequent steps. If unsuccessful, you will receive an error message that is intentionally quite generic. This is by design so that we do not leak any information (such as whether OIDC is configured, which claim failed, whether a service account is associated with the provider, etc.). + #### GitHub Actions Example ```yaml @@ -266,7 +237,7 @@ jobs: uses: actions/checkout@v4 - name: Authenticate with Cloudsmith via OIDC - uses: cloudsmith-io/cloudsmith-cli-action@v1.0.3 + uses: cloudsmith-io/cloudsmith-cli-action@v2 with: oidc-namespace: 'your-oidc-workspace' # Replace with your Cloudsmith workspace oidc-service-slug: 'your-service-account-slug' # Replace with the slug of your Cloudsmith service account diff --git a/src/content/authentication/setup-cloudsmith-to-authenticate-with-oidc-in-github-actions.mdx b/src/content/authentication/setup-cloudsmith-to-authenticate-with-oidc-in-github-actions.mdx index 4f632481..f32f3c63 100644 --- a/src/content/authentication/setup-cloudsmith-to-authenticate-with-oidc-in-github-actions.mdx +++ b/src/content/authentication/setup-cloudsmith-to-authenticate-with-oidc-in-github-actions.mdx @@ -70,7 +70,7 @@ permissions: ```yaml - name: Authenticate with Cloudsmith via OIDC - uses: cloudsmith-io/cloudsmith-cli-action@v1.0.3 + uses: cloudsmith-io/cloudsmith-cli-action@v2 with: oidc-namespace: 'your-workspace' # Your Cloudsmith Workspace oidc-service-slug: 'your-service-account-slug' # Your Cloudsmith service account slug @@ -104,7 +104,7 @@ jobs: # 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/cloudsmith-cli-action@v1.0.3 + uses: cloudsmith-io/cloudsmith-cli-action@v2 with: oidc-namespace: 'WORKSPACE' # Replace with your Cloudsmith workspace oidc-service-slug: 'SERVICE_ACCOUNT_SLUG' # Replace with your service account slug diff --git a/src/content/integrations/integrating-with-circleci.mdx b/src/content/integrations/integrating-with-circleci.mdx index cac4e5ac..1b99d7dd 100644 --- a/src/content/integrations/integrating-with-circleci.mdx +++ b/src/content/integrations/integrating-with-circleci.mdx @@ -37,129 +37,101 @@ And then include the orb: ```yaml orbs: - cloudsmith: cloudsmith/cloudsmith@1.0.6 + cloudsmith: cloudsmith/cloudsmith@2.0.0 ``` -Note that you can check the [releases page on github](https://github.com/cloudsmith-io/orb/releases) for our orb, [or the orb page](https://circleci.com/developer/orbs/orb/cloudsmith/cloudsmith) on CircleCI itself to find the latest version to use. +Note that you can check the [releases page on GitHub](https://github.com/cloudsmith-io/orb/releases) for our orb, [or the orb page](https://circleci.com/developer/orbs/orb/cloudsmith/cloudsmith) on CircleCI itself to find the latest version to use. -You'll need to configure authentication credentials for the orb if you're not planning to use OIDC to authenticate with. To do so, you can add an environment variable named `CLOUDSMITH_API_KEY` within the CircleCI settings page for your project: +### OIDC Authentication (recommended) - - -The orb (for now) requires that you have already built the package you wish to publish. Assuming you're publishing a Python library (though the same process applies to any package type), you'll want to run `setup.py sdist` as a step in your job: +The recommended approach is to authenticate via OIDC, install the CLI, and invoke it directly in your run steps. This uses short-lived tokens and avoids storing long-lived API keys: ```yaml -jobs: - publish: - executor: circleci/python:3.7 - steps: - - checkout - - run: - name: Build Python package - command: python setup.py sdist +version: 2.1 + +orbs: + cloudsmith: cloudsmith/cloudsmith@2.0.0 workflows: - cloudsmith_publish: + cloudsmith_oidc_publish: jobs: - publish -``` - -Once built, we can use the orb to easily publish the package. The orb provides a number of commands to make this process simpler. We'll first ensure the Cloudsmith CLi is configured and installed, then after we've built the package, publish it: -```yaml jobs: publish: - executor: circleci/python:3.7 + executor: cloudsmith/default steps: - checkout - - cloudsmith/ensure-api-key + - cloudsmith/authenticate-with-oidc: + organization: my-org + service-account: my-service-account - cloudsmith/install-cli - run: - name: Build Python package - command: python setup.py sdist - - cloudsmith/publish: - cloudsmith-repository: myorg/myrepo - package-path: dist/package-*.tar.gz - package-format: python + name: Build and publish Python package + command: | + pip install build + python -m build --wheel + cloudsmith push python my-org/my-repo dist/*.whl ``` -If using OIDC for authentication, ensure you're using at least version `1.0.6` of the Cloudsmith orb and add an extra step calling `authenticate-with-oidc` e.g. +The `authenticate-with-oidc` command exchanges a CircleCI OIDC token for a short-lived Cloudsmith API token, exported as `CLOUDSMITH_API_KEY`. Ensure OIDC is enabled in your CircleCI project settings (Project Settings → Advanced → Enable OpenID Connect Tokens). -``` -... +If you only need the API token and don't need to install the CLI, you can use `authenticate-with-oidc` on its own: + +```yaml jobs: - publish: - executor: circleci/python:3.7 + authenticate: + executor: cloudsmith/default steps: - checkout - cloudsmith/authenticate-with-oidc: - organization: - service-account: - - cloudsmith/ensure-api-key -... + organization: my-org + service-account: my-service-account + - run: + name: Call Cloudsmith API + command: | + curl -H "X-Api-Key: $CLOUDSMITH_API_KEY" \ + https://api.cloudsmith.io/user/self/ ``` -Putting this all together, we end up with a `.circleci/config.yaml` file which looks like so: +### API Key Authentication + +If OIDC is not available in your environment, you can authenticate with a static API key. Add an environment variable named `CLOUDSMITH_API_KEY` in your CircleCI project settings: + + + +Then use `ensure-api-key` to validate the key is set before running CLI commands: ```yaml version: 2.1 orbs: - cloudsmith: cloudsmith/cloudsmith@1.0.4 - -jobs: - publish: - executor: circleci/python:3.7 - steps: - - checkout - - cloudsmith/ensure-api-key - - cloudsmith/install-cli - - run: - name: Build Python package - command: python setup.py sdist - - cloudsmith/publish: - cloudsmith-repository: myorg/myrepo - package-path: dist/package-*.tar.gz - package-format: python + cloudsmith: cloudsmith/cloudsmith@2.0.0 workflows: cloudsmith_publish: jobs: - publish -``` - -## Manual integration - -Our official Orb provides simple integration for the majority of standard CI usecases, but we know that it won't fit every purpose. For additional flexibility users can mix and match commands provided by the orb and/or use the Cloudsmith CLI directly. - -For example, to use the orb to install and configure the CLI, but then use the CLI directly to publish to Cloudsmith, your configuration might look like so: - -```yaml -version: 2.1 - -orbs: - cloudsmith: cloudsmith/cloudsmith@1.0.4 jobs: publish: - executor: circleci/python:3.7 + executor: cloudsmith/default steps: - checkout - cloudsmith/ensure-api-key - cloudsmith/install-cli - run: - name: Build Python package - command: python setup.py bdist_wheel - - run: - name: Publish Python package - command: cloudsmith push python myorg/myrepo dist/my-package-0.1.0.whl - -workflows: - cloudsmith_publish: - jobs: - - publish + name: Build and publish Python package + command: | + pip install build + python -m build --wheel + cloudsmith push python my-org/my-repo dist/*.whl ``` + + The `cloudsmith/default` executor uses the `cimg/python` convenience image. If you need a different base image, you can specify your own executor and the orb commands will work in any environment that has the required dependencies (Python, curl, jq). + + ## Support As always, if you have any questions about integration or would like some general advice, please [contact support](https://cloudsmith.com/company/contact-us). diff --git a/src/content/integrations/integrating-with-github-actions.mdx b/src/content/integrations/integrating-with-github-actions.mdx index bb8a4a99..8afdc461 100644 --- a/src/content/integrations/integrating-with-github-actions.mdx +++ b/src/content/integrations/integrating-with-github-actions.mdx @@ -31,7 +31,7 @@ permissions: steps: - uses: actions/checkout@v4 - name: Authenticate & Install Cloudsmith CLI (OIDC) - uses: cloudsmith-io/cloudsmith-cli-action@v1 + uses: cloudsmith-io/cloudsmith-cli-action@v2 with: oidc-namespace: your-oidc-namespace oidc-service-slug: your-service-account-slug @@ -47,7 +47,7 @@ Use when you only need the token for API calls: ```yaml steps: - - uses: cloudsmith-io/cloudsmith-cli-action@v1 + - uses: cloudsmith-io/cloudsmith-cli-action@v2 with: oidc-namespace: your-oidc-namespace oidc-service-slug: your-service-account-slug @@ -64,7 +64,7 @@ Use for quick tests or legacy setups when OIDC isn’t available. steps: - uses: actions/checkout@v4 - name: Install Cloudsmith CLI (API Key) - uses: cloudsmith-io/cloudsmith-cli-action@v1 + uses: cloudsmith-io/cloudsmith-cli-action@v2 with: api-key: ${{ secrets.CLOUDSMITH_API_KEY }} ``` @@ -113,7 +113,7 @@ jobs: python -m pip install build python -m build - name: Install Cloudsmith CLI (OIDC) - uses: cloudsmith-io/cloudsmith-cli-action@v1 + uses: cloudsmith-io/cloudsmith-cli-action@v2 with: oidc-namespace: your-oidc-namespace oidc-service-slug: your-service-account-slug