Skip to content

Setup

Install GitHub App

First, you need to install Cirrus Runners GitHub App on your GitHub organization. Please follow this link in order to enable Cirrus Runners for repositories in your organization.

After successful installation of Cirrus Runners App you'll be redirected to a checkout page powered by Stripe. We require to provide billing information in advance but your billing cycle will start only after 10 days of free trial.

If you prefer other means of billing or would like an extended trial period please contact sales@cirruslabs.org.

Configuring Cirrus Runners

In order for Cirrus Runners to be used by your GitHub Actions workflow jobs, specify a desired image in the runs-on property:

jobs:
  macos:
    name: "Run on the fastest infrastructure"
    runs-on: ghcr.io/cirruslabs/macos-runner:sonoma
    steps:
      - uses: actions/checkout@v4
      - name: List Installed Xcodes
        run: xcodes installed
      - name: Select Xcode 16
        run: sudo xcodes select 16

jobs:
  linux-x86:
    name: "Run on the fastest infrastructure"
    runs-on: ghcr.io/cirruslabs/ubuntu-runner-amd64:22.04-md

jobs:
  linux-arm:
    name: "Run on the fastest infrastructure"
    runs-on: ghcr.io/cirruslabs/ubuntu-runner-arm64:22.04-md

jobs:
  linux-gpu:
    name: "Run on the fastest infrastructure"
    runs-on: ghcr.io/cirruslabs/ubuntu-runner-amd64-gpu:22.04

Available Images

For Linux runners, we provide an omnibus image that includes all necessary tools and dependencies for most use cases. These images are not 100% compatible with the GitHub Actions hosted runners, but we are working on improving compatibility. If your workflow didn't work out of the box, please let us know by creating an issue in the template repository used for creating the images.

For macOS runners, we provide images with different versions of macOS of Xcode pre-installed. You can find the list of available images in the similar template repository. We recommend to use ghcr.io/cirruslabs/macos-runner:sonoma image which contains 3 latest versions of Xcode pre-installed and xcodes tool to switch between them. This runner image starts your workflows instantly since it is pre-warmed on physical servers. Other ghcr.io/cirruslabs/macos-* images might take 10-15 seconds longer to start.

Resource Classes

By default, a single concurrent Cirrus Runner uses "large" CPU and Memory resources for a given operating system. It is possible to request more resources by adding -xl suffix to the image tag. Here is an example of an XL macOS runner configuration which will use 8 CPUs and 24GB of memory:

name: Tests
  jobs:
    test:
      runs-on: ghcr.io/cirruslabs/macos-runner:sonoma-xl

Note that an XL runner occupies double the concurrency available to your organization.

For Linux runners, it is also possible to request "medium" and "small" resource that will respectively occupy 0.5 and 0.25 concurrency available to your organization.

name: Tests
  jobs:
    test:
      runs-on: ghcr.io/cirruslabs/ubuntu-runner-amd64:22.04-md

name: Tests
  jobs:
    test:
      runs-on: ghcr.io/cirruslabs/ubuntu-runner-arm64:22.04-sm

Here is a table of all available resource classes per operating system:

Resource Class Suffix CPUs Memory Disk Concurrency
Large lg (default) 4 12 GB 130 1.00
Extra Large xl 8 24 GB 130 2.00
Resource Class Suffix CPUs Memory Disk Concurrency
Small sm 4 16 GB 40 0.25
Medium md 8 32 GB 80 0.50
Large lg (default) 16 64 GB 160 1.00
Extra Large xl 32 128 GB 320 2.00
Resource Class Suffix CPUs Memory Disk Concurrency
Small sm 4 12 GB 40 0.25
Medium md 8 24 GB 80 0.50
Large lg (default) 16 48 GB 160 1.00
Extra Large xl 32 96 GB 320 2.00
Resource Class Suffix CPUs Memory GPU Disk Concurrency
Large xl (default) 16 48 GB Nvidia RTX 4000 100 2.00

Speeding up the cache

If you are using the actions/cache action and noticing slower than usual saving or restoring times, you might consider trying out the cirruslabs/cache action instead.

It is a fork of actions/cache that is synced to the upstream on a daily basis and is identical to it except for a 5 lines patch that makes it prefer our own caching API, which delivers a noticeable speed boost.

When using the cirruslabs/cache action on GitHub infrastructure it falls back to actions/cache behaviour.

You can try it out by simply changing the actions to cirruslabs:

-- uses: actions/cache@v4
+- uses: cirruslabs/cache@v4
   with:
     path: node_modules
     key: node_modules

Each Cirrus Runner you subscribe to comes with 10GB of storage space. Files in this storage are automatically deleted after 100 days to make room for new ones. For example, if you have 20 Cirrus Runners, you have a total of 200GB of storage shared across all your repositories. If you go over that storage limit before the 100-day cleanup, the system will start deleting the oldest files first.

Advanced HTTP Cache Server

For most cases the regular cirruslabs/cache action mechanism is more than enough. But modern build systems like Gradle, Bazel and Pants can take advantage of remote caching. Remote caching is when a build system uploads and downloads intermediate results of a build execution while the build itself is still executing.

Cirrus Runners starts a local caching server and exposes it via CIRRUS_HTTP_CACHE_HOST environments variable. Caching server supports GET, POST, HEAD and DELETE requests to upload, download, check presence and delete artifacts.

For example running the following command:

curl -s -X POST --data-binary @myfolder.tar.gz http://$CIRRUS_HTTP_CACHE_HOST/name-key

will upload myfolder.tar.gz file to the cache with the key name-key.

Enabling Gradle Remote Build Cache

Cirrus HTTP Cache is compatible with Gradle Build Cache and can be enabled in settings.gradle.kts:

buildCache {
  // Check if Cirrus HTTP Cache is available
  val httpCacheHost = System.getenv("CIRRUS_HTTP_CACHE_HOST")
  if (httpCacheHost != null) {
    remote<HttpBuildCache> {
      url = uri("http://$httpCacheHost/")
      isEnabled = true
      // Push to cache only on the main branch
      isPush = System.getenv("GITHUB_REF_NAME") == "main"
    }
  } 
}

Don't forget to put org.gradle.caching=true into gradle.properties file or pass --build-cache to the gradle command.

Runners Execution

When workflows are executing you'll see Cirrus on-demand runners on your organization's settings page at https://github.com/organizations/ORGANIZATION/settings/actions/runners.

Note that Cirrus Runners will get added to the default runner group.

Using Cirrus Runners with public repositories

By default, only private repositories can access runners in a default runner group, but you can override this in your organization's settings:

https://github.com/organizations/ORGANIZATION/settings/actions/runner-groups/1

You can also get insights into the usage of Cirrus Runners by visiting the Cirrus Runners Dashboard.