> ## 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.

# Concepts

> The words Airship uses, and what each one means in your account and in your repository.

## The pieces

**Installation** `one GitHub organization or user`

The tenant. Installing the GitHub App creates one, and everything else —
connected clouds, activated repositories, runners, jobs, API tokens — belongs
to it. Every query, every cloud API call and every machine tag is scoped to
one installation.

**Activated repository** `an explicit switch`

A repository Airship will launch machines for. Installing the app is not
enough: activation is a separate, deliberate step, so an `airship.yaml`
committed to a repository nobody activated launches nothing. Public
repositories need a second choice, because their fork pull requests run
untrusted code.

**Runner definition** `an entry in airship.yaml`

A named description of a machine: its cloud, size, image, region and the
labels it serves. A definition is a recipe, not a machine — nothing exists
until a job asks for one of its labels.

**Label** `the airship- prefix`

How a job asks for a machine. Only labels starting with `airship-` are
looked up, so every other job on the repository is untouched and costs
nothing. See [Labels and runs-on](https://docs.airshipci.com/configuration/labels.md).

**Runner** `one machine, one job`

A single machine with a single-use GitHub registration. It takes one job and
the machine is destroyed. The **Runners** page shows each one's state and
instance ID.

**Job** `what GitHub asked for`

A `workflow_job` Airship was told about. The **Jobs** page shows what was
planned for each, which runner served it, or why none did.

**Plan** `an ordered list of attempts`

How Airship intends to serve one job: every combination of the definition's
[fallback lists](https://docs.airshipci.com/configuration/fallbacks.md), then any other definition
sharing the label. Fixed when the job is first seen queued.

**Idle runner pool** `machines waiting in advance`

Runners kept booted and registered so a job starts in seconds instead of
minutes. Still one job per machine: a pool runner that takes a job is
replaced straight away. See [Idle runners](https://docs.airshipci.com/performance/idle-runners.md).

**Organization runners** `the .airship repository`

Definitions in `airship.global.yaml` that every activated repository can
use, so machine shapes stop being copied between repositories. See
[Organization-wide runners](https://docs.airshipci.com/organization/runners.md).

**Access policy** `access.yaml`

Which repositories, teams, roles and people may use an expensive runner. See
[Access control](https://docs.airshipci.com/organization/access-control.md).

**Control plane** `the service`

What receives GitHub's webhooks, reads your config, launches and tears down
machines, and serves the dashboard and the API. Airship runs one for you, or
you [run your own](https://docs.airshipci.com/self-hosting/overview.md).

## The files

| File | Where | What it does |
| - | - | - |
| `airship.yaml` | The root of each activated repository | Defines that repository's runners. Read at a job's own commit |
| `airship.global.yaml` | The root of a `.airship` repository in the organization | Defines runners every activated repository can use |
| `access.yaml` | The root of the same `.airship` repository | Restricts who may use which organization runner |

## The labels a runner registers with

Every runner carries `self-hosted`, its architecture (`x64` or `arm64`), its
cloud (`aws`, `gcp`, `azure`), `cpu` or `gpu`, `airship`, and the labels the
definition lists. The runner software adds its own operating system label.

A job is served only when a definition covers **every** `airship-` label it
asks for, and the runner can satisfy the rest. A job asking for
`[airship-build, gpu]` needs a definition whose labels include `airship-build`
**and** which has a GPU.

## What costs money

Airship launches machines in your account; your cloud provider bills you for
them directly. The levers:

> **[max\_runners](https://docs.airshipci.com/organization/capacity.md)**
>
> The ceiling on live runners across every repository. The one number that
> bounds total spend.

> **[Spot capacity](https://docs.airshipci.com/configuration/fallbacks.md)**
>
> `preemptible: [true, false]` tries spot first and falls back to on-demand.

> **[Machine lifetime](https://docs.airshipci.com/how-it-works.md#runner-states)**
>
> Eight hours by default, enforced by the machine on itself.

> **[Idle pools](https://docs.airshipci.com/performance/idle-runners.md)**
>
> Warm machines cost money while they wait. `schedule:` windows keep that to
> working hours.


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