Cirrus CI Documentation

Cirrus CI offers different pricing models based on your repository type and infrastructure needs:

• Free Public Repositories: Free access to Cirrus Cloud Clusters for public repositories. You can also bring your own infrastructure or configure persistent workers.
• Private Personal Repositories: A $10/month plan providing access to community clusters for both public and private repositories, plus the ability to bring your own infrastructure or use persistent workers.
• Private Organization Repositories: Free access to community clusters for public repositories. For private repositories, you can use Compute Credits to access community clusters or Bring Your Own Infrastructure (which costs $10/seat/month).

Cirrus CI uses a powerful configuration format that supports advanced CI workflows. Key configuration features include:

• Matrix Builds: Run tasks across multiple combinations of parameters.
• Dependencies between tasks: Define execution order and requirements.
• Conditional Task Execution: Run tasks only when specific conditions are met.
• Local HTTP Cache: Speed up builds using cached assets.
• Dockerfile as a CI environment: Use a Dockerfile to define your build environment.
• Monorepo Support: Specialized functions for managing monorepos.

The Cirrus CI Service (including websites, API, and blog) is governed by the Terms of Service. By using the service, you agree to these terms. Key points include:

• Ownership: You retain all rights and ownership of your Customer Source Code. Cirrus Labs claims no ownership or control over it.
• Content: "Content" refers to data generated by Cirrus CI on your behalf (like metrics) and does not include your source code.
• Changes: Cirrus Labs may change terms or prices. For price changes, you will be notified at least 30 days in advance. Continued use of the service after changes constitutes acceptance.
• Termination: You can cancel your subscription at any time via the GitHub Marketplace. Cirrus Labs may terminate or suspend subscriptions at its discretion.

A task is the fundamental unit of work in Cirrus CI. It defines a sequence of instructions to execute within a specific execution environment.

Tasks can be named using the name field for rich, human-readable descriptions. While you can use the task_name: syntax as syntactic sugar, using a dedicated name field is recommended for complex names.

Note: Individual instructions within a task (like test_script) must be named using a prefix rather than a standalone name field.

task:
  name: Tests (macOS)
  test_script: ./run-tests.sh

Cirrus CI allows you to use Starlark to define tasks and logic instead of relying solely on declarative YAML. Starlark is a procedural programming language similar to Python that is ideal for embedding logic safely. It is used to generate configuration dynamically, such as parsing files in the repository or making HTTP requests to check build statuses.

Key benefits include:

• No compilation required.
• Instant execution on any platform via a Go-based interpreter.
• Built-in support for loading external modules for configuration sharing.

When tasks have complex names (e.g., names containing environment variables or matrix values), you can use the alias field to provide a short, stable name. This makes managing depends_on lists much easier.

task:
  name: Test Shard $TESTS_SPLIT
  alias: Tests
  env:
    matrix:
      TESTS_SPLIT: 1/3
      TESTS_SPLIT: 2/2
      TESTS_SPLIT: 3/3
  tests_script: ./.ci/tests.sh

deploy_task:
  depends_on: Tests
  script: ./.ci/deploy.sh

You can connect your own compute services or persistent workers to Cirrus CI to orchestrate workloads on your own hardware/cloud.

• Cost: Free for public repositories. For private repositories, it costs $10/seat/month (unless you have a Priority Support Subscription).
• Benefits: Full control over VM/container types, CPU/Memory allocation, and security (firewalls/access rules). You pay for CI within your existing cloud/GitHub bills.
• Cons: Requires manual configuration and maintenance of the infrastructure.

Cirrus CI can send POST requests to a configured WebHook URL when builds or tasks are updated.

• Event Identification: The X-Cirrus-Event header specifies whether the update is for a build or a task.
• Payload Structure: The JSON payload includes an action (created or updated), an optional old_status (for updated actions), and a data field.
• Data Retrieval: The data field contains information that can be queried via GraphQL using the repository, build, or task types.

{
  "action": "created" | "updated",
  "old_status": "FAILED",
  "data": ...
}

Compute credits allow you to use managed Cirrus Cloud Clusters without maintaining your own infrastructure. 1 credit equals 1 USD. Billing is per-second based on CPU time used.

Estimated costs per 1000 minutes of 1 virtual CPU:

• Linux: 3 credits
• FreeBSD: 3 credits
• Windows: 4 credits
• Apple Silicon: 15 credits

Benefits:

• No infrastructure maintenance.
• Per-second billing with no extra fees for storage or traffic.
• Orchestration costs are included (no additional seats required).

Limitations:

• No support for exotic hardware like GPUs, SSDs, or machines with 100+ cores.
• Less cost-efficient for very large teams.