Cirun GitHub Actions Setup: Connect Your Cloud and .cirun.yml

Cirun runs GitHub Actions runners inside your own cloud account. Setup has three parts: install the Cirun GitHub App, connect your cloud credentials on the Cirun dashboard, and add a .cirun.yml file to your repo that defines the runner. This guide walks through each step with a real AWS example. Config keys shown here are from Cirun's own docs; verify current syntax at docs.cirun.io as it may change.

Step 1: Install the Cirun GitHub App

Install the Cirun app from the GitHub Marketplace and grant it access to the repositories where you want managed runners. This lets Cirun register and deregister runners for your workflows.

Step 2: Connect your cloud credentials

On the Cirun dashboard, add cloud access for your provider (AWS, GCP, Azure, Oracle, DigitalOcean, Hetzner, OpenStack, or Vast.ai). Cirun authenticates to your cloud with the credentials you provide and launches instances in your account, so you pay your cloud provider directly. Grant an IAM identity with permission to create and terminate the instance types you plan to use.

Step 3: Add a .cirun.yml to your repo

Create .cirun.yml at the repository root. It defines one or more runners with a cloud, instance type, machine image, region, and labels. A minimal AWS example:

runners:
  - name: "aws-runner"
    cloud: "aws"
    instance_type: "t2.medium"
    machine_image: "ami-06fd8a495a537da8b"
    preemptible: false
    labels:
      - "cirun-aws-runner"

Step 4: Reference the runner from your workflow

In your GitHub Actions workflow, point runs-on at the Cirun label. Cirun appends the run id so each job gets a fresh runner:

jobs:
  build:
    runs-on: "cirun-aws-runner--${{ github.run_id }}"
    steps:
      - uses: actions/checkout@v4
      - run: make build

Optional: preemptible and GPU

Set preemptible: true to use lower-cost spot instances on clouds that support them (GCP, AWS). For GPU jobs, add a gpu key (for example gpu: "nvidia-tesla-t4") and a GPU-capable instance type and image. Cirun installs GPU drivers automatically for supported configurations.

If you would rather skip the cloud setup

The steps above require you to own and operate a cloud account: credentials, IAM, quotas, and the cloud bill. If you want managed runners with none of that, Latchkey is fully managed - you swap the runs-on label to a Latchkey runner and there is no cloud account to connect. It also adds self-healing so transient failures retry automatically and runs up to ~58% under GitHub-hosted per minute.