### Docker Config JSON Example

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/linux.md

An example of the `~/.docker/config.json` file structure after a successful Docker login to a private registry.

```json
{
  "auths": {
    "container-registry.oracle.com": {
      "auth": "...."
    }
  }
}
```

--------------------------------

### AWS SSM Get Parameters CLI Example

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/supported-computing-services.md

This command demonstrates how Cirrus CI resolves AMIs using AWS System Manager Parameter Store.

```bash
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/arm64/recommended
```

--------------------------------

### Install Tart and Run VM with Softnet

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/blog/posts/2022-07-07-isolating-network-between-tarts-macos-virtual-machines.md

Install Tart using Homebrew and then run a macOS virtual machine with Softnet enabled using the --with-softnet flag. This method requires passwordless sudo to be configured.

```bash
brew install cirruslabs/cli/tart
tart clone ghcr.io/cirruslabs/macos-monterey-base:latest monterey-base
tart run --with-softnet monterey-base
```

--------------------------------

### Windows Container with Install Script

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/windows.md

Configure a Windows container and specify an `install_script` for package management using Chocolatey.

```yaml
windows_container:
  image: cirrusci/windowsservercore:2019

windows_task:
  install_script: choco install -y ...
  ...

```

--------------------------------

### Get Build by SHA

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/api.md

Example of how to retrieve a build for a specific SHA of a given repository using the Cirrus CI GraphQL API.

```APIDOC
## Get Build by SHA

### Description
Retrieves build information for a specific commit SHA within a repository.

### Method
`POST`

### Endpoint
`https://api.cirrus-ci.com/graphql`

### Parameters
#### Query Parameters
None

#### Request Body
```json
{
  "query": "query BuildBySHAQuery($owner: String!, $name: String!, $SHA: String) { searchBuilds(repositoryOwner: $owner, repositoryName: $name, SHA: $SHA) { id } }",
  "variables": {
    "owner": "ORGANIZATION",
    "name": "REPOSITORY NAME",
    "SHA": "SOME SHA"
  }
}
```

### Request Example
```bash
curl -X POST --data 
'{ 
  "query": "query BuildBySHAQuery($owner: String!, $name: String!, $SHA: String) { searchBuilds(repositoryOwner: $owner, repositoryName: $name, SHA: $SHA) { id } }", 
  "variables": { 
    "owner": "ORGANIZATION", 
    "name": "REPOSITORY NAME", 
    "SHA": "SOME SHA" 
  } 
}' 
https://api.cirrus-ci.com/graphql | python -m json.tool
```

### Response
#### Success Response (200)
Returns a JSON object containing the build ID.

```json
{
  "id": "build_id"
}
```
```

--------------------------------

### Configure FreeBSD GCE Instance

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/supported-computing-services.md

Example configuration for running tasks on a FreeBSD instance on Google Compute Engine. Explicitly sets the platform to 'FreeBSD'.

```yaml
gce_instance:
  image_project: freebsd-org-cloud-dev
  image_family: freebsd-14-3
  platform: FreeBSD
  zone: us-central1-a
  cpu: 8
  memory: 40GB
  disk: 50

task:
  script: printenv
```

--------------------------------

### Overriding Default Command for Additional Container (amd64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/writing-tasks.md

This example demonstrates how to override the default command of an additional container for amd64. It specifies a custom command to start the MySQL server on a different port.

```yaml
container:
  image: golang:latest
  additional_containers:
    - name: mysql
      image: mysql:latest
      port: 7777
      command: mysqld --port 7777
      env:
        MYSQL_ROOT_PASSWORD: ""
        MYSQL_ALLOW_EMPTY_PASSWORD: "yes"
```

--------------------------------

### Share Task Configuration with YAML Aliases

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/tips-and-tricks.md

Define reusable task configurations using YAML aliases to avoid repetition. This example shares 'only_if' conditions and environment setup.

```yaml
# Define a node anywhere in YAML file to create an alias. Make sure the name doesn't clash with an existing keyword.
regular_task_template: &REGULAR_TASK_TEMPLATE
  only_if: $CIRRUS_BRANCH == 'master' || $CIRRUS_TAG != '' || $CIRRUS_PR != ''
  env:
    FRAMEWORK_PATH: "${HOME}/framework"
  install_framework_script: curl https://example.com/framework.tar | tar -C "${FRAMEWORK_PATH}" -x

task:
  # This operator will insert REGULAR_TASK_TEMPLATE at this point in the task node.
  << : *REGULAR_TASK_TEMPLATE
  name: linux
  container:
    image: alpine:latest
  test_script: ls "${FRAMEWORK_PATH}"

task:
  << : *REGULAR_TASK_TEMPLATE
  name: osx
  macos_instance:
    image: catalina-xcode
  test_script: ls -w "${FRAMEWORK_PATH}"
```

--------------------------------

### Cache with Fingerprint Script Example

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/writing-tasks.md

An example of a cache instruction that uses a 'fingerprint_script' to generate a cache key based on the content of 'yarn.lock'.

```yaml
node_modules_cache:
  folder: node_modules
  fingerprint_script: cat yarn.lock
```

--------------------------------

### Configure Windows GCE Instance

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/supported-computing-services.md

Example configuration for running tasks on a Windows instance on Google Compute Engine. Explicitly sets the platform to 'windows'.

```yaml
gce_instance:
  image_project: windows-cloud
  image_family: windows-2016-core
  platform: windows
  zone: us-central1-a
  cpu: 8
  memory: 40GB
  disk: 20

task:
  script: run-ci.bat
```

--------------------------------

### Configure Basic GCE Instance

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/supported-computing-services.md

Example configuration for scheduling tasks on a Google Compute Engine instance. Specifies image details, architecture, zone, and resource allocation.

```yaml
gce_instance:
  image_project: ubuntu-os-cloud
  image_family: ubuntu-2204-lts-arm64
  architecture: arm64 # optional. By default, amd64 is assumed.
  zone: us-central1-a
  cpu: 8
  memory: 40GB
  disk: 60
  use_ssd: true # defaults to false
  hostname: ubuntu.local

task:
  script: ./run-ci.sh
```

--------------------------------

### Running MySQL as an Additional Container (arm64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/writing-tasks.md

This example shows how to configure an additional MySQL container for an arm64 architecture. It is similar to the amd64 version but uses the `arm_container` keyword.

```yaml
arm_container:
  image: golang:latest
  additional_containers:
    - name: mysql
      image: mysql:latest
      port: 3306
      cpu: 1.0
      memory: 512Mi
      env:
        MYSQL_ROOT_PASSWORD: ""
        MYSQL_ALLOW_EMPTY_PASSWORD: "yes"
```

--------------------------------

### Running MySQL as an Additional Container (amd64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/writing-tasks.md

This example demonstrates how to configure an additional MySQL container for an amd64 architecture. It specifies the image, port, resources, and environment variables for the MySQL instance.

```yaml
container:
  image: golang:latest
  additional_containers:
    - name: mysql
      image: mysql:latest
      port: 3306
      cpu: 1.0
      memory: 512Mi
      env:
        MYSQL_ROOT_PASSWORD: ""
        MYSQL_ALLOW_EMPTY_PASSWORD: "yes"
```

--------------------------------

### Configure macOS Instance

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/macOS.md

Use the `macos_instance` directive in your `.cirrus.yml` file to specify the macOS image for your virtual machine. This example uses the Sonoma image.

```yaml
macos_instance:
  image: ghcr.io/cirruslabs/macos-runner:sonoma

task:
  script: echo "Hello World from macOS!"
```

--------------------------------

### Cache with Fingerprint Key Example

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/writing-tasks.md

An example of a cache instruction that uses a static 'fingerprint_key' for cache identification.

```yaml
node_modules_cache:
  folder: node_modules
  fingerprint_key: 2038-01-20
```

--------------------------------

### Android Build Task with Hardware Emulator

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Configure this task when your Android tests require a hardware-accelerated emulator. This setup includes installing system images, creating an AVD, and waiting for the emulator to boot.

```yaml
container:
  image: ghcr.io/cirruslabs/android-sdk:30
  cpu: 4
  memory: 12G
  kvm: true

check_android_task:
  install_emulator_script:
    sdkmanager --install "system-images;android-30;google_apis;x86"
  create_avd_script:
    echo no | avdmanager create avd --force
      -n emulator
      -k "system-images;android-30;google_apis;x86"
  start_avd_background_script:
    $ANDROID_HOME/emulator/emulator
      -avd emulator
      -no-audio
      -no-boot-anim
      -gpu swiftshader_indirect
      -no-snapshot
      -no-window
  # assemble while emulator is starting
  assemble_instrumented_tests_script:
    ./gradlew assembleDebugAndroidTest
  wait_for_avd_script:
    adb wait-for-device shell 'while [[ -z $(getprop sys.boot_completed) ]]; do sleep 3; done; input keyevent 82'
  check_script: ./gradlew check connectedCheck
```

--------------------------------

### AWS EC2 Describe Images CLI Example

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/supported-computing-services.md

This command illustrates how Cirrus CI filters AMIs using the EC2 DescribeImages API.

```bash
aws ec2 describe-images --filters "Name=name,Values=ubuntu/images/hvm-ssd/ubuntu-jammy-22.04-amd64-server-*"
```

--------------------------------

### C++ Build Task (arm64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Example of a C++ build task using the official GCC Docker image for arm64 architecture. Assumes a Makefile for tests.

```yaml
arm_container:
  image: gcc:latest
task:
  tests_script: make tests
```

--------------------------------

### Multi-arch Build Setup with Buildx

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/docker-builder-vm.md

Configure the Docker Builder VM to use buildx for multi-architecture builds. This involves setting up a buildx builder instance and then using `docker buildx build`.

```yaml
docker_builder:
  setup_script:
    - docker buildx create --name multibuilder
    - docker buildx use multibuilder
    - docker buildx inspect --bootstrap
  build_script: docker buildx build --platform linux/amd64,linux/arm64 --tag myrepo/foo:$CIRRUS_TAG .

```

--------------------------------

### GolangCI Lint Task (amd64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Example .cirrus.yml task for running GolangCI Lint on amd64. Uses the official GolangCI Lint Docker image and configures artifact reporting.

```yaml
task:
  name: GolangCI Lint
  container:
    image: golangci/golangci-lint:latest
  run_script: golangci-lint run -v --out-format json > lint-report.json
  always:
    golangci_artifacts:
      path: lint-report.json
      type: text/json
      format: golangci
```

--------------------------------

### GolangCI Lint Task (arm64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Example .cirrus.yml task for running GolangCI Lint on arm64. Uses the official GolangCI Lint Docker image and configures artifact reporting.

```yaml
task:
  name: GolangCI Lint
  arm_container:
    image: golangci/golangci-lint:latest
  run_script: golangci-lint run -v --out-format json > lint-report.json
  always:
    golangci_artifacts:
      path: lint-report.json
      type: text/json
      format: golangci
```

--------------------------------

### Build PyPI Packages with Python (arm64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Builds PyPI sdist and wheel packages using Python for arm64 architecture. Includes pip cache setup.

```yaml
arm_container:
  image: python:slim

build_package_test_task:
  pip_cache:
    folder: ~/.cache/pip
    fingerprint_script: echo $PYTHON_VERSION
    populate_script: python3 -m pip install --upgrade setuptools wheel
  build_package_test_script: python3 setup.py sdist bdist_wheel
```

--------------------------------

### Granular Environment Variable Control with Matrix

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/writing-tasks.md

Demonstrates fine-grained control over environment variables using `matrix`. This example creates 4 tasks, each with a specific combination of `ANDROID_CLT_VERSION` and `JDK_PACKAGE`.

```yaml
task:
  name: matrixdemo
  container:
    image: ubuntu:24.04
  env:
    matrix:
      - ANDROID_CLT_VERSION: 9123335 # v8, latest compatible with JDK 8+
        JDK_PACKAGE: openjdk-8-jdk
      - ANDROID_CLT_VERSION: 9862592 # v10, latest compatible with JDK 11+
        JDK_PACKAGE: openjdk-11-jdk
      - ANDROID_CLT_VERSION: 11479570 # v13, latest compatible with JDK 17+
        JDK_PACKAGE: openjdk-17-jdk
      - ANDROID_CLT_VERSION: 11479570 # v13, latest compatible with JDK 17+
        JDK_PACKAGE: openjdk-21-jdk
    info_script:
      - echo "Building Android SDK with Android Command-line tools $ANDROID_CLT_VERSION and JDK $JDK_PACKAGE"
```

--------------------------------

### Mapping Ports for Additional Containers

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/writing-tasks.md

This example shows how to map a container port to a host port using the `port` field. It also demonstrates using the `ports` field to specify multiple port mappings.

```yaml
ports:
  - 8080
  - 3306
```

--------------------------------

### C++ Build Task (amd64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Example of a C++ build task using the official GCC Docker image for amd64 architecture. Assumes a Makefile for tests.

```yaml
container:
  image: gcc:latest
task:
  tests_script: make tests
```

--------------------------------

### Go Project Test Task (arm64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Example .cirrus.yml for testing Go projects using Go Modules on an arm64 architecture. Utilizes official Go Docker images and caches Go modules.

```yaml
arm_container:
  image: golang:latest

test_task:
  modules_cache:
    fingerprint_script: cat go.sum
    folder: $GOPATH/pkg/mod
  get_script: go get ./...
  build_script: go build ./...
  test_script: go test ./...
```

--------------------------------

### Go Project Test Task (amd64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Example .cirrus.yml for testing Go projects using Go Modules on an amd64 architecture. Utilizes official Go Docker images and caches Go modules.

```yaml
container:
  image: golang:latest

test_task:
  modules_cache:
    fingerprint_script: cat go.sum
    folder: $GOPATH/pkg/mod
  get_script: go get ./...
  build_script: go build ./...
  test_script: go test ./...
```

--------------------------------

### Build PyPI Packages with Python (amd64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Builds PyPI sdist and wheel packages using Python for amd64 architecture. Includes pip cache setup.

```yaml
container:
  image: python:slim

build_package_test_task:
  pip_cache:
    folder: ~/.cache/pip
    fingerprint_script: echo $PYTHON_VERSION
    populate_script: python3 -m pip install --upgrade setuptools wheel
  build_package_test_script: python3 setup.py sdist bdist_wheel
```

--------------------------------

### Flutter Project Configuration

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Example .cirrus.yml for a Flutter project. Uses a pre-built Docker image with Flutter and Dart SDK, caches pub dependencies, and runs tests.

```yaml
container:
  image: ghcr.io/cirruslabs/flutter:latest

test_task:
  pub_cache:
    folder: ~/.pub-cache
  test_script: flutter test --machine > report.json
  always:
    report_artifacts:
      path: report.json
      format: flutter
```

--------------------------------

### Elixir Test Task (amd64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Example .cirrus.yml for running Elixir tests on an amd64 architecture. Uses official Elixir Docker image and manages dependencies with mix.

```yaml
test_task:
  container:
    image: elixir:latest
  mix_cache:
    folder: deps
    fingerprint_script: cat mix.lock
    populate_script: mix deps.get
  compile_script: mix compile
  test_script: mix test
```

--------------------------------

### Elixir Test Task (arm64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Example .cirrus.yml for running Elixir tests on an arm64 architecture. Uses official Elixir Docker image and manages dependencies with mix.

```yaml
test_task:
  arm_container:
    image: elixir:latest
  mix_cache:
    folder: deps
    fingerprint_script: cat mix.lock
    populate_script: mix deps.get
  compile_script: mix compile
  test_script: mix test
```

--------------------------------

### Erlang Test Task (arm64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Example .cirrus.yml for running Erlang tests on an arm64 architecture. Uses official Erlang Docker image and manages dependencies with rebar3.

```yaml
test_task:
  arm_container:
    image: erlang:latest
  rebar3_cache:
    folder: _build
    fingerprint_script: cat rebar.lock
    populate_script: rebar3 compile --deps_only
  compile_script: rebar3 compile
  test_script: rebar3 ct
```

--------------------------------

### Create EKS Cluster via AWS CLI

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/supported-computing-services.md

Example command to create an EKS cluster using the AWS CLI. This is useful for ensuring the cluster is created with the correct user.

```bash
$: aws sts get-caller-identity
{
    "UserId": "...",
    "Account": "...",
    "Arn": "USER_USED_BY_CIRRUS_CI"
}
$: aws eks --region $REGION \
    create-cluster --name cirrus-ci \
    --role-arn ... \
    --resources-vpc-config subnetIds=...,securityGroupIds=...
```

--------------------------------

### Erlang Test Task (amd64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Example .cirrus.yml for running Erlang tests on an amd64 architecture. Uses official Erlang Docker image and manages dependencies with rebar3.

```yaml
test_task:
  container:
    image: erlang:latest
  rebar3_cache:
    folder: _build
    fingerprint_script: cat rebar.lock
    populate_script: rebar3 compile --deps_only
  compile_script: rebar3 compile
  test_script: rebar3 ct
```

--------------------------------

### Accessing Cirrus CI Environment Variables

Source: https://context7.com/cirruslabs/cirrus-ci-docs/llms.txt

Example of how to access and display key Cirrus CI environment variables within a task. This helps in understanding the build context.

```yaml
# .cirrus.yml — Example using key environment variables
container:
  image: alpine:latest

info_task:
  info_script: |
    echo "Build ID:      $CIRRUS_BUILD_ID"
    echo "Repo:          $CIRRUS_REPO_FULL_NAME"
    echo "Branch:        $CIRRUS_BRANCH"
    echo "SHA:           $CIRRUS_CHANGE_IN_REPO"
    echo "PR:            ${CIRRUS_PR:-not a PR}"
    echo "Tag:           ${CIRRUS_TAG:-not a tag}"
    echo "OS:            $CIRRUS_OS"
    echo "CPUs:          $CIRRUS_CPU"
    echo "Default branch:$CIRRUS_DEFAULT_BRANCH"

# Key variables:
# CIRRUS_BUILD_ID         — unique build identifier
# CIRRUS_TASK_ID          — unique task identifier
# CIRRUS_REPO_FULL_NAME   — "org/repo"

```

--------------------------------

### Ruby Gem Caching for arm64

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Cache installed gems based on Ruby version and Gemfile.lock for arm64 architecture. This setup ensures faster subsequent builds by reusing cached gems.

```yaml
arm_container:
  image: ruby:latest

rspec_task:
  bundle_cache:
    folder: /usr/local/bundle
    fingerprint_script:
      - echo $RUBY_VERSION
      - cat Gemfile.lock
    populate_script: bundle install
  rspec_script: bundle exec rspec --format json --out rspec.json
  always:
    rspec_report_artifacts:
      path: rspec.json
      type: text/json
      format: rspec
```

--------------------------------

### Configure FreeBSD Instance

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/FreeBSD.md

Use `freebsd_instance` in your `.cirrus.yml` to specify the desired FreeBSD image family for your virtual machine.

```yaml
freebsd_instance:
  image_family: freebsd-14-3

task:
  install_script: pkg install -y ...
  script: ...
```

--------------------------------

### Ruby Gem Caching for amd64

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Cache installed gems based on Ruby version and Gemfile.lock for amd64 architecture. This setup ensures faster subsequent builds by reusing cached gems.

```yaml
container:
  image: ruby:latest

rspec_task:
  bundle_cache:
    folder: /usr/local/bundle
    fingerprint_script:
      - echo $RUBY_VERSION
      - cat Gemfile.lock
    populate_script: bundle install
  rspec_script: bundle exec rspec --format json --out rspec.json
  always:
    rspec_report_artifacts:
      path: rspec.json
      type: text/json
      format: rspec
```

--------------------------------

### Configure Spot Instances for GCE

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/supported-computing-services.md

Configure `gce_instance` to use spot instances by setting the `spot` key to a boolean expression. This allows for cost savings on non-critical tasks, such as builds on non-master branches, while tolerating the risk of preemption.

```yaml
gce_instance:
  image_project: my-project
  image_name: my-custom-image-with-docker
  zone: us-central1-a
  spot: $CIRRUS_BRANCH != "master"
```

--------------------------------

### Audit Event WebHook Payload Example

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/api.md

An example of an audit event payload for a user re-running a task with an attached terminal. It includes mutation details, task ID, and actor information.

```json
{
  "action": "created" | "updated",
  "data": {
    "id": "uuid-uuid-uuid-uuid",
    "type": "graphql.mutation",
    "timestamp": ...,
    "data": "{\n  \"mutationName\": \"TaskReRun\",\n  \"taskId\": \"1\",\n  \"attachTerminal\": true,\n  \"newTaskId\": 2\n}",
    "actor": {
      "id": "..." // internal to Cirrus CI user Id
    },
    "repository": {
      "id": "123",
      "owner": "ACME",
      "name": "super-project",
      "isPrivate": true
    }
  }
}
```

--------------------------------

### Define a Docker Pipe with Build and Validate Steps

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/docker-pipe.md

Use the `pipe` and `steps` fields to define a Docker Pipe. Each step specifies a Docker `image` and a `script` to execute within that container. This example builds documentation and then validates links.

```yaml
pipe:
  name: Build Site and Validate Links
  steps:
    - image: squidfunk/mkdocs-material:latest
      build_script: mkdocs build
    - image: raviqqe/liche:latest # links validation tool in a separate container
      validate_script: /liche --document-root=site --recursive site/
```

--------------------------------

### Ruby Gem Caching without Gemfile.lock for arm64

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Cache installed gems for arm64 architecture when Gemfile.lock is not committed. Uses `install_script` for `bundle install` and fingerprints based on Gemfile and gemspec.

```yaml
arm_container:
  image: ruby:latest

rspec_task:
  bundle_cache:
    folder: /usr/local/bundle
    fingerprint_script:
      - echo $RUBY_VERSION
      - cat Gemfile
      - cat *.gemspec
  install_script: bundle install # or `update` for the freshest bundle
  rspec_script: bundle exec rspec
```

--------------------------------

### Ruby Gem Caching without Gemfile.lock for amd64

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Cache installed gems for amd64 architecture when Gemfile.lock is not committed. Uses `install_script` for `bundle install` and fingerprints based on Gemfile and gemspec.

```yaml
container:
  image: ruby:latest

rspec_task:
  bundle_cache:
    folder: /usr/local/bundle
    fingerprint_script:
      - echo $RUBY_VERSION
      - cat Gemfile
      - cat *.gemspec
  install_script: bundle install # or `update` for the freshest bundle
  rspec_script: bundle exec rspec
```

--------------------------------

### Store Oracle Cloud Credentials

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/supported-computing-services.md

Example of storing Oracle Cloud credentials as an encrypted variable in Cirrus CI configuration.

```yaml
oracle_credentials: ENCRYPTED[qwerty239abc]
```

--------------------------------

### Go Project Build and Test with Artifacts

Source: https://context7.com/cirruslabs/cirrus-ci-docs/llms.txt

Configures a Go project to build, test, and upload artifacts. Includes caching and test report generation.

```yaml
container:
  image: golang:latest

build_and_test_task:
  modules_cache:
    folder: $GOPATH/pkg/mod
    fingerprint_script: cat go.sum
  build_script: go build -o ./bin/myapp ./...
  test_script: go test -v ./... 2>&1 | go-junit-report > test-results.xml
  on_failure:
    debug_script: go vet ./...
  always:
    junit_artifacts:
      path: "**/test-results.xml"
      format: junit
      type: text/xml
  binaries_artifacts:
    path: "bin/*"
    type: application/octet-stream
```

--------------------------------

### Configure Azure Credentials in Cirrus CI

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/supported-computing-services.md

Example of how to add encrypted Azure credentials to your `.cirrus.yml` file. The `azure_credentials` should be an encrypted variable.

```yaml
azure_credentials: ENCRYPTED[qwerty239abc]
```

--------------------------------

### Configure Yarn Cache for amd64

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/writing-tasks.md

Configures a cache for 'node_modules' on amd64 using 'yarn.lock' for fingerprinting. 'yarn install' is executed unconditionally.

```yaml
test_task:
  container:
    image: node:latest
  node_modules_cache:
    folder: node_modules
    fingerprint_script: cat yarn.lock
  install_script: yarn install
  test_script: yarn run test
```

--------------------------------

### Configure Auto-Cancellation of Tasks

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/writing-tasks.md

Control the auto-cancellation of tasks based on branch conditions. This example disables auto-cancellation for the master branch and release branches.

```yaml
task:
  auto_cancellation: $CIRRUS_BRANCH != 'master' && $CIRRUS_BRANCH !=~ 'release/.*'
  ...
```

--------------------------------

### Configure EKS Task in Cirrus CI

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/supported-computing-services.md

Example configuration for scheduling tasks on an EKS cluster using Cirrus CI. The `nodeSelectorTerms` are optional.

```yaml
task:
  eks_container:
    image: node:latest
    region: us-east-1
    cluster_name: cirrus-ci
    nodeSelectorTerms: # optional
      - matchExpressions:
        - key: eks.amazonaws.com/capacityType
          operator: In
          values:
            - SPOT
  script: ./run-ci.sh
```

--------------------------------

### Dockerfile COPY instruction example

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/docker-builder-vm.md

When using `COPY` instructions in your Dockerfile, specify the full path to avoid cache invalidation issues and potential security risks. This ensures that only explicitly copied files contribute to the cache key.

```dockerfile
FROM python:3

COPY requirements.txt /tmp/
RUN pip install --requirement /tmp/requirements.txt
```

--------------------------------

### OCI Object Storage Lifecycle Policy

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/supported-computing-services.md

Example policy for Oracle Cloud Infrastructure Object Storage to manage lifecycle policies. This is for the `us-ashburn-1` region.

```text
Allow service objectstorage-us-ashburn-1 to manage object-family in tenancy
```

--------------------------------

### Configure Azure Container Instances

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/supported-computing-services.md

Configure Azure Container Instances for running CI tasks. Ensure `azure_credentials` are set up beforehand.

```yaml
azure_container_instance:
  image: cirrusci/windowsservercore:2016
  resource_group: CirrusCI
  region: westus
  platform: windows
  cpu: 4
  memory: 12G
```

--------------------------------

### Cirrus CI Build Status Badge URL Formats

Source: https://context7.com/cirruslabs/cirrus-ci-docs/llms.txt

Reference for constructing badge URLs, specifying organization, repository, and optional parameters for branch or task filtering.

```bash
# Badge URL formats:
# https://api.cirrus-ci.com/github/<ORG>/<REPO>.svg
# https://api.cirrus-ci.com/github/<ORG>/<REPO>.svg?branch=<BRANCH>
# https://api.cirrus-ci.com/github/<ORG>/<REPO>.svg?task=<TASK_NAME>
# https://api.cirrus-ci.com/github/<ORG>/<REPO>.svg?task=<TASK>&script=<SCRIPT>
```

--------------------------------

### Ruby Test Parallelization with Knapsack Pro

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Configure multiple shards for parallel test execution using Knapsack Pro. This example demonstrates setting up four shards to potentially speed up test runs by a factor of four.

```yaml
task:
  matrix:
    name: rspec (shard 1)
    name: rspec (shard 2)
    name: rspec (shard 3)
    name: rspec (shard 4)
  bundle_cache:
    folder: /usr/local/bundle
    fingerprint_script: cat Gemfile.lock
    populate_script: bundle install
  rspec_script: bundle exec rake knapsack_pro:rspec
```

--------------------------------

### Cache Python Packages with pip (amd64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Caches pip installed packages based on requirements.txt for amd64 architecture. Use for Python projects with pip.

```yaml
container:
  image: python:slim

test_task:
  pip_cache:
    folder: ~/.cache/pip
    fingerprint_script: echo $PYTHON_VERSION && cat requirements.txt
    populate_script: pip install -r requirements.txt
  test_script: pytest
```

--------------------------------

### Get Workload Identity Pool ID

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/supported-computing-services.md

Retrieve the full ID of the created Workload Identity Pool. This ID is required for subsequent configuration steps.

```bash
gcloud iam workload-identity-pools describe "ci-pool" \
  --project="${PROJECT_ID}" \
  --location="global" \
  --format="value(name)"
```

--------------------------------

### Configure Container Resources (arm64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/linux.md

Set custom CPU and memory limits for arm64 containers. Default is 2 CPUs and 4GB memory.

```yaml
arm_container:
  image: openjdk:latest
  cpu: 4
  memory: 12G

task:
  script: ...
```

--------------------------------

### Run Script in Background

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/writing-tasks.md

Utilize `background_script` to execute commands without blocking subsequent task instructions. This is useful for starting services like emulators.

```yaml
android_test_task:
  start_emulator_background_script: emulator -avd test -no-audio -no-window
  wait_for_emulator_to_boot_script: adb wait-for-device
  test_script: gradle test
```

--------------------------------

### Basic Matrix Modification for arm64

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/writing-tasks.md

Similar to the amd64 example, this defines a task that runs against two different Node.js versions but uses `arm_container` for arm64 architecture.

```yaml
test_task:
  arm_container:
    matrix:
      - image: node:latest
      - image: node:lts
  test_script: yarn run test
```

--------------------------------

### Cirrus CI Configuration for Go Project

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/blog/posts/2020-10-07-cirrus-cli.md

Example of a .cirrus.yml file defining tasks for a Go project, including environment matrix, Docker image, caching, and build/test scripts. This configuration can be used with Cirrus CLI.

```yaml
task:
  env:
    matrix:
      VERSION: 1.15
      VERSION: 1.14
  name: Tests (Go $VERSION)
  container:
    image: golang:$VERSION # official Go Docker image
  modules_cache:
    folder: $GOPATH/pkg/mod
    fingerprint_script: cat go.sum
  get_script: go get ./...
  build_script: go build ./...
  test_script: go test ./...
```

--------------------------------

### Container Isolation Configuration

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/persistent-workers.md

Set up a persistent worker to run tasks in a containerized environment using Docker or Podman. This example mounts host directories into the container.

```yaml
persistent_worker:
  isolation:
    container:
      image: debian:latest
      cpu: 24
      memory: 128G
      volumes:
        - /path/on/host:/path/in/container
        - /tmp/persistent-cache:/tmp/cache:ro

task:
  script: uname -a
```

--------------------------------

### Gradle Properties for CI

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

A sample gradle.properties file with common settings for CI environments, including daemon, caching, parallel execution, and on-demand configuration.

```properties
org.gradle.daemon=true
org.gradle.caching=true
org.gradle.parallel=true
org.gradle.configureondemand=true
org.gradle.jvmargs=-Dfile.encoding=UTF-8
```

--------------------------------

### Cache Python Packages with pip (arm64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Caches pip installed packages based on requirements.txt for arm64 architecture. Use for Python projects with pip on arm64.

```yaml
arm_container:
  image: python:slim

test_task:
  pip_cache:
    folder: ~/.cache/pip
    fingerprint_script: echo $PYTHON_VERSION && cat requirements.txt
    populate_script: pip install -r requirements.txt
  test_script: pytest
```

--------------------------------

### Configure Container Resources (amd64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/linux.md

Set custom CPU and memory limits for amd64 containers. Default is 2 CPUs and 4GB memory.

```yaml
container:
  image: openjdk:latest
  cpu: 4
  memory: 12G

task:
  script: ...
```

--------------------------------

### View and Buy Compute Credits

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/pricing.md

Navigate to your organization's settings page to check your current compute credit balance and purchase more.

```bash
https://cirrus-ci.com/settings/github/MY-ORGANIZATION
```

--------------------------------

### Override Root-Level Environment Variables

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/writing-tasks.md

Task-level environment variables take precedence over root-level variables. This example shows how a task's PATH overrides the global PATH.

```yaml
env:
  PATH: /sdk/bin:${PATH}

echo_task:
  env:
    PATH: /opt/bin:${PATH}
  echo_script: echo $PATH
```

--------------------------------

### Configure Maven Build

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Sets up the Maven build environment using the official Maven Docker image and configures Maven caching for faster builds.

```yaml
container:
  image: maven:latest

task:
  name: Cirrus CI
  maven_cache:
    folder: ~/.m2
  test_script: mvn test -B
```

```yaml
arm_container:
  image: maven:latest

task:
  name: Cirrus CI
  maven_cache:
    folder: ~/.m2
  test_script: mvn test -B
```

--------------------------------

### Rust Build and Test Caching for amd64

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/examples.md

Example of a Rust build configuration using official Docker images. Caches crates and target artifacts based on `Cargo.lock`.

```yaml
container:
  image: rust:latest

test_task:
  registry_cache:
    folder: $CARGO_HOME/registry
    fingerprint_script: cat Cargo.lock
  target_cache:
    folder: target
    fingerprint_script:
      - rustc --version
      - cat Cargo.lock
  build_script: cargo build
  test_script: cargo test
  before_cache_script: rm -rf $CARGO_HOME/registry/index
```

--------------------------------

### Generate Multiple Tasks with main()

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/programming-tasks.md

Use the `main()` function to return a list of task objects. Each object defines a container and a script to be executed.

```python
def main():
    return [
      {
        "container": {
          "image": "debian:latest"
        },
        "script": "make test"
      },
      {
        "container": {
          "image": "debian:latest"
        },
        "script": "make build"
      }
    ]
```

--------------------------------

### Emit Raw YAML String with main()

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/programming-tasks.md

Return a string containing YAML configuration from `main()` to append directly to `.cirrus.yml`. Useful for splitting configuration across files.

```python
load("cirrus", "env", "fs")

def main(ctx):
  if env.get("CIRRUS_TAG") != None:
    return fs.read(".cirrus.release.yml")
  if env.get("CIRRUS_PR") != None:
    return fs.read(".cirrus.pr.yml")

  return fs.read(".cirrus.pr.yml") + fs.read(".cirrus.e2e.yml")
```

--------------------------------

### Node.js Build Configuration (arm64)

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/quick-start.md

Configure a Node.js build task for arm64 architecture. Includes caching node_modules and running tests.

```yaml
arm_container:
  image: node:latest

check_task:
  node_modules_cache:
    folder: node_modules
    fingerprint_script: cat yarn.lock
    populate_script: yarn install
  test_script: yarn test
```

--------------------------------

### Monorepo Task Generation with Starlark

Source: https://context7.com/cirruslabs/cirrus-ci-docs/llms.txt

Configure Starlark to generate tasks only for changed service directories in a monorepo. This example uses `changes_include_only` to skip tasks if only documentation changes.

```python
# .cirrus.star — Monorepo: generate tasks only for changed service directories
load("cirrus", "fs", "env", "changes_include_only")

SERVICES = ["api", "frontend", "worker", "scheduler"]

def service_task(name, image):
    return {
        "name": "Test %s" % name,
        "container": {"image": image},
        name + "_cache": {
            "folder": "%s/node_modules" % name,
            "fingerprint_script": "cat %s/package-lock.json" % name,
            "populate_script": "cd %s && npm ci" % name,
        },
        "test_script": "cd %s && npm test" % name,
    }

def main(ctx):
    # Skip all tasks if only docs changed
    if changes_include_only("docs/**", "*.md"):
        return []

    tasks = []
    for svc in SERVICES:
        # Only include service task if its directory exists and has changes
        if fs.isdir(svc) and changes_include("%s/**" % svc):
            image = "node:lts" if svc != "worker" else "python:3.12-slim"
            tasks.append(service_task(svc, image))

    # Always run integration tests on main branch
    if env.get("CIRRUS_BRANCH") == "main" and len(tasks) > 0:
        tasks.append({
            "name": "Integration Tests",
            "depends_on": ["Test %s" % s for s in SERVICES if fs.isdir(s)],
            "container": {"image": "docker:latest"},
            "integration_script": "docker compose up --abort-on-container-exit",
        })

    return tasks

```

--------------------------------

### Configure Node.js Cache for arm64

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/writing-tasks.md

Defines a cache for the 'node_modules' folder on arm64 architecture. It uses a fingerprint script to determine cache validity and installs dependencies only when necessary.

```yaml
test_task:
  arm_container:
    image: node:latest
  node_modules_cache:
    folder: node_modules
    reupload_on_changes: false # since there is a fingerprint script
    fingerprint_script:
      - echo $CIRRUS_OS
      - node --version
      - cat package-lock.json
    populate_script: 
      - npm install
  test_script: npm run test
```

--------------------------------

### Create File from Configuration Contents

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/writing-tasks.md

Populate a file directly from the `.cirrus.yml` configuration using the `from_contents` directive.

```yaml
task:
  git_config_file:
    path: /root/.gitconfig
    from_contents: |
      [user]
        name = John Doe
        email = john@example.com
```

--------------------------------

### Configure Node.js Cache for amd64

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/writing-tasks.md

Defines a cache for the 'node_modules' folder on amd64 architecture. It uses a fingerprint script to determine cache validity and installs dependencies only when necessary.

```yaml
test_task:
  container:
    image: node:latest
  node_modules_cache:
    folder: node_modules
    reupload_on_changes: false # since there is a fingerprint script
    fingerprint_script:
      - echo $CIRRUS_OS
      - node --version
      - cat package-lock.json
    populate_script: 
      - npm install
  test_script: npm run test
```

--------------------------------

### Generate Base64 Encoded Credentials

Source: https://github.com/cirruslabs/cirrus-ci-docs/blob/master/docs/guide/linux.md

Manually create a Base64 encoded string of your username and Personal Access Token (PAT) if your Docker installation uses a credentials store.

```bash
echo $USERNAME:$PAT | base64
```