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:
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:
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.
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 | 25 | 0.25 |
Medium | md |
8 | 32 GB | 50 | 0.50 |
Large | lg (default) |
16 | 64 GB | 100 | 1.00 |
Extra Large | xl |
32 | 128 GB | 200 | 2.00 |
Resource Class | Suffix | CPUs | Memory | Disk | Concurrency |
---|---|---|---|---|---|
Small | sm |
4 | 12 GB | 25 | 0.25 |
Medium | md |
8 | 24 GB | 50 | 0.50 |
Large | lg (default) |
16 | 48 GB | 100 | 1.00 |
Extra Large | xl |
32 | 96 GB | 200 | 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
:
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:
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:
You can also get insights into the usage of Cirrus Runners by visiting the Cirrus Runners Dashboard.