Use the CLI with a public repository

2 minute read

Authentication between the CloudBees Smart Tests CLI and CloudBees Smart Tests API typically requires an API key. However, API keys cannot be used for open-source projects in public repositories since anyone can retrieve an API key by opening a pull request.

To solve this problem for open-source projects, CloudBees Smart Tests offers another authentication mechanism called tokenless authentication. Instead of using a static token, tokenless authentication uses a CI/CD service provider’s public API to verify if tests are actually running in CI. With this feature, OSS contributors can analyze and optimize test execution without a static CloudBees Smart Tests API token.

In November 2022 CloudBees Smart Tests added support for OpenID Connect for authentication.

If tokenless authentication was implemented before November 2022, refer to Update tokenless authentication to use GitHub OIDC.

Set up tokenless authentication

Prerequisites

If your project is open source, and you want to use CloudBees Smart Tests;

  • The open-source project needs to be hosted in a public GitHub repository.

  • The open-source project needs to use GitHub Actions for CloudBees CI.

Preparation

  1. Sign up and create your Organization and Workspace.

  2. Contact us to enable tokenless authentication for your project. We need to know your CloudBees Smart Tests organization, CloudBees Smart Tests workspace, and GitHub repository URL.

  3. Update your GitHub Actions YAML.

  4. Start using CloudBees Smart Tests in your open-source project.

GitHub Actions YAML configuration

Once tokenless authentication is enabled for your project, do the following:

  1. Configure environment variables in your CI pipeline:

    1. SMART_TESTS_ORGANIZATION: CloudBees Smart Tests organization name

    2. SMART_TESTS_WORKSPACE: CloudBees Smart Tests workspace name

    3. EXPERIMENTAL_GITHUB_OIDC_TOKEN_AUTH: Set this to 1

  2. Add the permissions section of your GitHub Actions YAML file.

Tokenless authentication relies on OpenID Connect (OIDC) tokens. To use an OIDC token in GitHub Actions, you need to configure permissions to retrieve it. As described in the GitHub Help Article, id-token: write permission needs to be added.

This permission can be added for one job or to the entire workflow:

name: Verify Smart Tests tokenless authentication

on:
  pull_request:
    paths:
      - gradle/**

env:
  SMART_TESTS_ORGANIZATION: "examples"
  SMART_TESTS_WORKSPACE: "gradle"
  EXPERIMENTAL_GITHUB_OIDC_TOKEN_AUTH: 1

permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v2
      - name: Set up JDK 1.8
        uses: actions/setup-java@v1
        with:
          java-version: 1.8

      - name: {PRODUCT}
        run: |
          pip3 install --user smart-tests~=1.0
          export PATH=~/.local/bin:$PATH
          smart-tests verify
        working-directory: ./gradle
▼

About OpenID Connect (OIDC)

In November 2022 CloudBees Smart Tests added support for OpenID Connect for authentication.

If tokenless authentication was implemented before November 2022, refer to Update tokenless authentication to use GitHub OIDC.
Introduction
Update tokenless authentication to use GitHub OIDC