Running Kurtosis on your local machine is nice, but the real power of the platform comes when it’s executed as part of CI. This guide will walk you through setting up Kurtosis in your CI environment.
You’ll need the Kurtosis CLI inside your CI environment. This can be accomplished by following the installation instructions for whichever package manager your CI container uses.
While it’s fine to prompt a user for their username and password when Kurtosis is run on the local machine, this method is insecure when executing Kurtosis on CI. Fortunately, our auth system provides a system for handling this called “machine-to-machine auth”. In the machine-to-machine flow, a client ID and a client secret are stored within the CI environment’s secrets and passed in to every CI job. Kurtosis uses these credentials to retrieve a token from the auth provider, which allows Kurtosis execution to proceed.
The client ID and secret are created by the Kurtosis team on the backend, so if you don’t have one already then reach out to firstname.lastname@example.org to discuss pricing.
WARNING: Make sure you store your client ID and secret in a secure place! Anyone with the credentials could impersonate you to Kurtosis, which would use up any usage-based credits on your behalf.
Now that you have your client credentials, you’ll need to pass them in to your CI environment as environment variables. The route for doing so will be particular to your CI server, so do a Google search for “define YOUR_CI_TOOL secrets”. Once done, you’ll need to pass the appropriate environment variables to Kurtosis. The
kurtosis.sh script has parameters for receiving the client ID and credentials, so run
kurtosis.sh --help to see what flags you need to pass in (or
build-and-run.sh all --help if it’s wrapping
kurtosis.sh in your instance).
Because the client credentials are secrets, they cannot be made available to builds of untrusted PRs (i.e. PRs from untrusted contributors, often submitted from forks) else there’s a risk that the untrusted PR maliciously prints them. This means that CI builds for untrusted PRs will fail. This is a tough problem for the entire the open-source community, but a decent workaround exists for repos on Github:
actions-comment-runGithub Action to your repo with these instructions. WARNING: If your repo is inside an organization, you should add the usernames of your repo administrators to the
allowed-usersconfig key. This is due to a bug in Github where “owners” of repos inside an organization don’t actually get the Github
OWNERrole (see this ticket for details).
Then, whenever an untrusted PR is submitted to your repo, a repo owner should:
actions-merge-preview/...branch; because the repo owner is trusted, secrets will be passed to CI and the CI build will proceed
This allows you to require untrusted code to pass a review before it runs (thereby securing your secrets) while still preserving the safety of CI.