Cirrus CLI is a tool for running containerized tasks reproducibly in any environment. Most commonly, Cirrus tasks are used as part of continuous integration workflows but can also be used as part of local development process as a hermetic replacement of helper scripts/Makefiles. Cirrus CLI runs your tasks locally the same way they are executed in CI or on your colleague's machine. Immutability of containers ensures the tasks will be executed the same way years from now regardless what versions of packages you'll have locally.
Cirrus CLI reuses the same YAML configuration format as Cirrus CI which allows to reuse a large list of examples created by Cirrus CI community.
Note: Cirrus CLI can be used in any environment that has Docker or Podman installed. It can be your laptop or any CI system you already have like Jenkins, GitHub Actions, Travis CI, etc. With Cirrus CLI it's no longer a requirement to use Cirrus CI in order to benefit from Cirrus configuration format that we (Cirrus Labs) have crafted for so long and really proud of.
Here is an example of .cirrus.yml
configuration file for testing a Go application with several Go versions:
task:
env:
matrix:
VERSION: 1.21
VERSION: 1.22
name: Tests (Go $VERSION)
container:
image: golang:$VERSION
modules_cache:
fingerprint_script: cat go.sum
folder: $GOPATH/pkg/mod
get_script: go get ./...
build_script: go build ./...
test_script: go test ./...
Note: container:
implies the amd64
architecture. If you're running on arm64
, please use with the arm_container
instead.
To run Cirrus tasks, simply switch to a directory where the .cirrus.yml
is located and run:
cirrus run
By default, working directory will be rsync
ed into a container while respecting .gitignore
configuration. This makes sure Cirrus Tasks are executed from a clean state only with source code
changes.
In case rsync
-ing the whole working directory is too costly, you can pass a --dirty
flag which
will result in all operations being done against the actual working directory (and not it's rsync
ed copy):
cirrus run --dirty Lint
Since most linters and code-analysis tools are read-only by their nature there is no need in extra precautions and
the potentially costly rsync
-ing can be safely avoided.
It is also possible to run a particular task by name:
cirrus run "Tests (Go 1.15)"
Or pass some extra environment variables with -e
flag:
cirrus run -e CIRRUS_TAG="test-release" Release
Note: Cirrus CLI only supports Linux container
and
macos_instance
VMs at the moment. Linux containers support the
Dockerfile as a CI environment feature.
To validate a Cirrus configuration, simply switch to a directory where the .cirrus.yml
is located and run:
cirrus validate
By default, Cirrus CLI stores blob artifacts produced by the cache instruction in the user-specific cached data folder. Similar to Cirrus Cloud the CLI can use a caching HTTP server for more efficient sharing of cached artifacts between tasks executed on different physical hosts.
Caching HTTP server should support a single /<key>
REST endpoint with PUT
, GET
and HEAD
methods available for
uploading, downloading and checking availability of a cached artifact under <key>
key respectively. There are reference
implementations of such HTTP servers for Google Cloud Storage and
AWS S3 and Azure's Blob Storage.
To start using your own HTTP caching server simply pass it's hostname as CIRRUS_HTTP_CACHE_HOST
to run
command:
cirrus run --environment CIRRUS_HTTP_CACHE_HOST=http-cache-host.internal:8080
Cirrus CLI aims to run in different environments, but in some environments we choose to provide more usability at the cost of some security trade-offs:
rsync
) run unconfinedPlease open an issue if your use-case requires a different approach.