> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airshipci.com/llms.txt
> Use this file to discover all available pages before exploring further.

# airship.yaml

> The file that defines your runners: every field, what it accepts, and what each cloud does with it.

`airship.yaml` lives at the root of each activated repository and describes
the machines that repository can ask for. Anything Airship does not recognise
is an error naming the field, so a typo fails the check rather than quietly
doing nothing.

```yaml airship.yaml theme={null}
runners:
  - name: build
    cloud: aws
    instance_type: [c7i.xlarge, m7i.xlarge, c7a.xlarge]  # tried in order
    machine_image: ami-0123456789abcdef0   # or ubuntu2204 / ubuntu2404
    region: us-east-1
    preemptible: [true, true, false]       # zipped with instance_type
    labels: [airship-build]
    extra_config:
      BlockDeviceMappings:
        - VolumeSize: 100
          VolumeType: gp3
          Iops: 6000
          Throughput: 1000
      env_vars:
        CARGO_INCREMENTAL: "0"
      cache: true
    idle:
      replicas: 2
```

## Fields

**name** `string` *required*

Unique within the file. Letters, digits, `.`, `_` and `-`.

**cloud** `string` *required*

`aws`, `gcp` or `azure`. The named cloud must be connected, or jobs for this
definition are skipped with *No cloud*.

**instance\_type** `string | string[]` *required*

An EC2 instance type (`c7i.xlarge`), a Compute Engine machine type
(`n2-standard-4`), or an Azure VM size as the API spells it
(`Standard_D4s_v5`). See [Machine types](https://docs.airshipci.com/configuration/machines.md).

**machine\_image** `string | mapping | list` (default: ubuntu2204)

What to boot. Each cloud accepts its own forms, plus the `ubuntu2204` and
`ubuntu2404` aliases for Canonical's newest image for the architecture. See
[Machine images](https://docs.airshipci.com/configuration/images.md).

**region** `string | string[]`

An AWS region; a Google Cloud **zone or region**; an Azure region as the API
spells it. Defaults to the connected cloud's default region.

**preemptible** `boolean | boolean[]` (default: false)

Spot capacity. Cheaper, and reclaimable — pair it with an on-demand
fallback. See [Fallbacks](https://docs.airshipci.com/configuration/fallbacks.md).

**labels** `string[]` *required*

The `runs-on` labels this runner serves. Every one must start with
`airship-`. See [Labels and runs-on](https://docs.airshipci.com/configuration/labels.md).

**gpu** `string | false`

A GPU name. Installs the NVIDIA driver on Ubuntu images that lack one and
adds the `gpu` label. `false`, `no` or `null` turns it off. See
[GPUs](https://docs.airshipci.com/configuration/machines.md#gpus).

**extra\_config** `mapping`

Everything cloud-specific: disks, networking, environment, caching. Keys
belonging to another cloud are refused by name, so a definition copied
between clouds fails on the first wrong key rather than silently ignoring
it.

**idle** `mapping`

Keep runners booted and registered in advance. Exactly one of `replicas`,
`schedule` or `usage_based`. See [Idle
runners](https://docs.airshipci.com/performance/idle-runners.md).

## extra\_config

Each key below is documented on the page that covers the thing it changes.

| Key | Clouds | What it changes |
| - | - | - |
| `cache` | AWS | [Cache acceleration](https://docs.airshipci.com/performance/caching.md) |
| `env_vars` | All | [Environment](https://docs.airshipci.com/configuration/environment.md#environment-variables) |
| `provision_via` | All | [Provisioning from your own image](https://docs.airshipci.com/configuration/environment.md#provisioning-from-your-image) |
| `run_as`, `runner_user`, `runner_path` | All | [Windows runners](https://docs.airshipci.com/configuration/windows.md) |
| `BlockDeviceMappings` | AWS | [Disks](https://docs.airshipci.com/configuration/storage.md#aws) |
| `SubnetId`, `SecurityGroupIds` | AWS | [Networking](https://docs.airshipci.com/configuration/networking.md#aws) |
| `IamInstanceProfile` | AWS | [Cloud identity](https://docs.airshipci.com/configuration/environment.md#cloud-identity) |
| `baseDisk`, `additionalDisk`, `existingDisk` | Google Cloud | [Disks](https://docs.airshipci.com/configuration/storage.md#google-cloud) |
| `networkInterfaces`, `project_id` | Google Cloud | [Networking](https://docs.airshipci.com/configuration/networking.md#google-cloud) |
| `serviceAccounts` | Google Cloud | [Cloud identity](https://docs.airshipci.com/configuration/environment.md#cloud-identity) |
| `scheduling` | Google Cloud | [Host maintenance](https://docs.airshipci.com/configuration/machines.md#host-maintenance) |
| `storageProfile` | Azure | [Disks](https://docs.airshipci.com/configuration/storage.md#azure) |
| `enable_public_ip` | Google Cloud, Azure | [Networking](https://docs.airshipci.com/configuration/networking.md) |

## Which file a job reads

A job reads `airship.yaml` **at its own commit**, so a branch or a pull
request can try a new machine type before it is merged.

[Idle runners](https://docs.airshipci.com/performance/idle-runners.md) are the exception: they are read
from the default branch only, since they exist before any job does. A push to
the default branch updates them within a reconcile pass.

A job is planned once, when GitHub first reports it queued. Editing the file
afterwards does not change how a waiting job is served.

## Checking a file before you commit it

The **Repositories** page has a checker that parses a file and shows the
machines it would plan — cheaper than a push. The [developer
API](https://docs.airshipci.com/api-reference/introduction.md) exposes the same check, so you can wire it
into a workflow of its own.

> [!TIP]
>
> A definition that covers several labels, and several definitions sharing one
> label, are both allowed. Two definitions sharing a label become one fallback
> chain, in file order.

## A fuller example

```yaml airship.yaml theme={null}
runners:
  # The everyday builder: spot first, on-demand second, a second family third.
  - name: build
    cloud: aws
    instance_type: [c7i.2xlarge, c7i.2xlarge, m7i.2xlarge]
    preemptible:   [true,        false,       false]
    region: eu-west-1
    labels: [airship-build]
    extra_config:
      BlockDeviceMappings:
        - VolumeSize: 100
          VolumeType: gp3
          Iops: 6000
          Throughput: 1000
      cache: true

  # Arm, for the second half of the release matrix.
  - name: build-arm
    cloud: aws
    instance_type: c7g.2xlarge
    region: eu-west-1
    labels: [airship-build-arm]

  # A GPU box someone waits on, so keep two warm in working hours.
  - name: gpu
    cloud: gcp
    instance_type: n1-standard-8
    gpu: nvidia-tesla-t4
    region: us-central1-b
    labels: [airship-gpu]
    idle:
      schedule:
        - day: mon-fri
          time: 9-18
          timezone: Europe/Berlin
          replicas: 2
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.