Project maintained by kurtosis-tech Hosted on GitHub Pages — Theme by mattgraham

Running in CI

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.

Installing The CLI

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.

Machine-to-Machine Auth

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 inquiries@kurtosistech.com 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.

Using Client Credentials

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).

Client Credentials & Untrusted PRs

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:

  1. Add the actions-comment-run Github 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-users config key. This is due to a bug in Github where “owners” of repos inside an organization don’t actually get the Github OWNER role (see this ticket for details).
  2. Copy the codeblock inside the “PR merge preview” header
  3. Store it as one of your “Saved Replies” in Github

Then, whenever an untrusted PR is submitted to your repo, a repo owner should:

  1. Review the code carefully to make sure no secrets are being printed
  2. Post a comment with the saved reply from above, which will trigger the Github Actions bot to create a copy of the changes on a new branch with a name like actions-merge-preview/ORIGINAL-BRANCH-NAME
  3. Open a PR with this actions-merge-preview/... branch; because the repo owner is trusted, secrets will be passed to CI and the CI build will proceed
  4. Inform the third-party contributor about the new PR so they can see the build status and make any necessary changes
  5. If the third-party contributor pushes any more changes, re-review them for any secret-leaking and re-post the same saved reply to update the trusted PR

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.

Back to index