# Deploying through Pilot

A deploy is a new container image for a workload. Send it to Pilot and it is rolled out like any other change: checked against the fleet spec, written to the one resource that runs the workload, followed by that resource's health check, and undone automatically if the check fails. It is recorded in the ledger under your name.

Nothing else on the resource is touched. If Pilot raised the instance limit an hour ago, the deploy does not put the old limit back.

## From a terminal or any CI

```bash
export INFRAPILOT_URL=https://infrapilot.fly
export INFRAPILOT_TOKEN=<a workspace API token>
infrapilot deploy api ghcr.io/acme/api:1.4.2
```

`api` is the workload's name in the fleet spec (or a resource's logical name). The image is any reference your cloud can pull: `registry/repository:tag` or `registry/repository@sha256:<digest>`. Prefer a digest or a unique tag over `latest`: a tag that does not change is not a deploy.

The command waits for the outcome:

| Exit code | Meaning |
| --- | --- |
| `0` | deployed: the new image is live (or the workload already ran it) |
| `1` | not deployed: a rule refused it, or the health check failed and the previous image is running again |
| `2` | the request was wrong: an unknown workload, a bad image reference, a rejected token |
| `3` | no outcome before `--timeout` (default 900 seconds); the deploy may still finish, see the ledger |

Options: `--container <name>` when the resource runs more than one container (otherwise the one named after the workload), `--timeout <seconds>`, `--no-wait`, `--workspace <id>`.

The token comes from the dashboard: Settings, API tokens. It is read from the environment only, never from an argument.

## From GitHub Actions

```yaml
- uses: <the Infrapilot deploy action>
  with:
    workload: api
    image: ghcr.io/acme/api:${{ github.sha }}
    url: ${{ vars.INFRAPILOT_URL }}
    token: ${{ secrets.INFRAPILOT_TOKEN }}
```

The step fails unless the new image is live, so a rolled-back deploy fails the workflow.

## Over the API

```bash
curl -s -X POST https://infrapilot.fly/api/v1/deploy \
  -H "Authorization: Bearer $INFRAPILOT_TOKEN" -H "Content-Type: application/json" \
  -d '{"workload": "api", "image": "ghcr.io/acme/api:1.4.2"}'
# {"ok": true, "deploy": "cmd_...", "status_url": "https://infrapilot.fly/api/v1/deploy/cmd_..."}

curl -s -H "Authorization: Bearer $INFRAPILOT_TOKEN" https://infrapilot.fly/api/v1/deploy/cmd_...
# {"done": true, "ok": true, "status": "settled", "txn": "tx_...", "node": "shop/api", "reasons": []}
```

`status` is the engine's: `settled` (live), `unchanged` (already running that image), `rolled_back` (health check failed, previous image restored), `rejected` (a rule refused it; `reasons` says which), `not_planned` (the workload or image could not be resolved).

## What can refuse a deploy

- **Level observe.** Nothing is changed through Infrapilot at that level, deploys included.
- **A protected resource**, or a property a provider controller owns.
- **The health check.** For a service this is the provider's own readiness (a Cloud Run revision that becomes Ready, a Container App that provisions and runs, an ECS deployment that completes with healthy targets). An image that never becomes ready is rolled back.

A deploy is your change, not Pilot's, so the limits on what Pilot may tune do not apply to it, and at level `propose` it does not wait for a second approval.
