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

# Quickstart

> Connect a cloud, activate a repository, and run your first job on a machine you own.

This walks the shortest path to a green job: AWS, one machine type, no
caching. Everything here applies to [Google Cloud](https://docs.airshipci.com/clouds/google-cloud.md) and
[Azure](https://docs.airshipci.com/clouds/azure.md) too — only the credential differs.

> [!NOTE]
>
> You need admin on a GitHub organization (to install the app and activate a
> repository) and permission to create a credential in a cloud account. Those
> are often two different people.

**1. Install the GitHub App**

Sign in at [app.airshipci.com](https://app.airshipci.com) and install the
Airship app on your organization. Grant it one repository to start — you
can add more later without reinstalling.

The app asks to read `airship.yaml`, to read job and runner metadata, and
to register and remove runners. It never gets your Actions secrets.
[What each permission is for](https://docs.airshipci.com/self-hosting/github-app.md#permissions).

**2. Create a cloud credential**

In AWS, create an IAM user with an access key. The quick version is
`AmazonEC2FullAccess`:

```bash theme={null}
aws iam create-user --user-name airship-runners
aws iam attach-user-policy --user-name airship-runners \
  --policy-arn arn:aws:iam::aws:policy/AmazonEC2FullAccess
aws iam create-access-key --user-name airship-runners
```

Keep the output. You paste it once and Airship never shows it again.

> [!TIP]
>
> In an account shared with production workloads, use the scoped policy in
> [Amazon Web Services](https://docs.airshipci.com/clouds/aws.md#the-iam-policy) instead. Its terminate
> permission is conditioned on Airship's own tag, so the credential cannot
> destroy a machine it did not create.

**3. Connect the cloud**

Open **Cloud → AWS** in the dashboard, paste the access key ID and secret,
and pick the default region — where runners launch when a definition names
none.

Airship verifies the credential with the cloud before storing it, and
shows you the account ID and principal it belongs to so you can confirm it
is the one you meant.

**4. Activate the repository**

Open **Repositories** and switch your repository on.

This is deliberately separate from installing the app: an `airship.yaml`
in a repository nobody activated launches nothing, so a config file can
never start spending money on its own.

**5. Commit a runner definition**

Add `airship.yaml` to the repository root:

```yaml airship.yaml theme={null}
runners:
  - name: build
    cloud: aws
    instance_type: c7i.2xlarge
    region: eu-west-1
    labels: [airship-build]
```

Then point a job at it:

```yaml .github/workflows/ci.yml theme={null}
name: CI
on: push

jobs:
  test:
    runs-on: airship-build--${{ github.run_id }}
    steps:
      - uses: actions/checkout@v4
      - run: nproc && free -g && df -h /
```

The `--${{ github.run_id }}` suffix makes the runner register under a label
unique to that workflow run, so GitHub can only hand it a job from that
run. Use it everywhere except with [idle
runners](https://docs.airshipci.com/performance/idle-runners.md), which exist before a run does.

> [!TIP]
>
> **Repositories** has a config checker that validates a file and shows the
> machines it would plan. Cheaper than a push.

**6. Push, and watch it happen**

| Where | What you should see |
| - | - |
| **Jobs** | The job queued within a second or two, with the machine Airship planned for it |
| **Runners** | A runner moving `pending → launching → running → busy`, with its instance ID |
| EC2 console | One instance tagged `airship:installation`, with no inbound security group rules |
| The job log | Your steps, on a runner labelled `self-hosted`, `x64`, `aws`, `airship` |
| EC2 console, again | The instance terminated within seconds of the job finishing |

The first job in a repository usually waits a minute or two for the
machine to boot and register. [Idle
runners](https://docs.airshipci.com/performance/idle-runners.md) remove that wait; a [custom
image](https://docs.airshipci.com/performance/custom-images.md) shortens it.

## If the job stays queued

The **Jobs** page says why in plain words — *Not activated*, *No cloud*, *No
runner serves the labels*, *Config problem*. Each reason and its fix is in
[Troubleshooting](https://docs.airshipci.com/troubleshooting.md#why-a-job-was-not-run). The **Events** page
carries your cloud's own error message when a launch fails.

## Worth doing in the first week

> **[Set a concurrency cap](https://docs.airshipci.com/organization/capacity.md)**
>
> `max_runners` is the one number that bounds total spend. Set it below your
> cloud's vCPU quota.

> **[Cancel a job mid-run](https://docs.airshipci.com/how-it-works.md#when-things-go-wrong)**
>
> Then check that no machine survives it. That behaviour is what everything
> else rests on.

> **[Turn on cache acceleration](https://docs.airshipci.com/performance/caching.md)**
>
> One line of config, and `actions/cache` starts reading from a bucket in
> your account.

> **[Add spot with a fallback](https://docs.airshipci.com/configuration/fallbacks.md)**
>
> Try spot first, fall back to on-demand, and let Airship walk the list.


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