Cirun .cirun.yml Config Errors: Runner Not Created

Cirun reads a .cirun.yml file at your repository root to decide what runner to launch. If that file is malformed, missing a required key, or its labels do not match your workflow, no runner is created. This page covers the common .cirun.yml mistakes. Verify the current schema at docs.cirun.io/reference/yaml.

Confirm the required keys

Each runner in the runners array typically needs name, cloud, instance_type, machine_image, and region, plus labels. Missing one of these, or using an unsupported cloud value, stops runner creation.

Match labels to runs-on exactly

The label in .cirun.yml must match the runs-on value in your workflow. Cirun's pattern appends the run id, so a runner labeled cirun-aws-runner is referenced as runs-on: "cirun-aws-runner--${{ github.run_id }}". A mismatch here is a common cause of jobs that never pick up a runner.

# .cirun.yml
runners:
  - name: "aws-runner"
    cloud: "aws"
    instance_type: "t2.medium"
    machine_image: "ami-06fd8a495a537da8b"
    region: "us-east-1"
    labels:
      - "cirun-aws-runner"

# workflow
jobs:
  build:
    runs-on: "cirun-aws-runner--${{ github.run_id }}"

Watch for YAML formatting mistakes

Indentation errors, tabs instead of spaces, or quoting problems will invalidate the file. Run it through a YAML linter, and keep the runners key as a list of mappings.

Verify image and instance validity

An instance_type or machine_image that does not exist in the target region (or a gpu key on a non-GPU instance) will pass YAML validation but fail at launch. Confirm these values are valid for your cloud and region.

A model with less config to drift

With a fully-managed option like Latchkey, there is no per-repo runner definition file to keep in sync with cloud images and regions - you point runs-on at a managed label and the provider handles the rest. That removes config drift as a failure mode. The trade-off is less direct control over the exact machine image and cloud.

Related guides