Targets and runs

Targets are where a deployment goes and what values it uses there. Runs are individual executions, with live logs, step status, and history.

Targets

A target is one concrete place a deployment goes — a client’s account, a staging environment, a region. Create targets on a deployment’s page; each needs a name in the same lowercase-and-hyphens style as deployment names, and an optional description.

Every target stores its own values for the deployment’s configuration variables, encrypted at rest, and keeps its own run history. The same aws-production deployment can have client-acme, client-globex, and internal-staging targets, each with different credentials and regions, all running the same steps.

Readiness

The deployment page lists targets with their state:

• Ready to deploy — every required, active configuration variable has a value or a default. Clicking the row opens the target; the row’s button deploys directly.
• Needs N values — something is missing or invalid. The button opens the target instead, where the form marks what still needs input.

Readiness only considers configuration variables. Deploy-time variables are supplied when a deploy starts and are never “missing” beforehand.

The target page

The target page is organized around the thing you do most, deploying:

1. Deploy — the button, disabled until the target is ready, and a note on what is still needed when it is not.
2. Latest outputs — the outputs of the most recent successful run, with copy buttons.
3. Run history — every run against this target, live-updating while one is active.
4. Variables — the form. Edit, save, and scroll back up to deploy.
5. Target settings — rename, describe, and for Keel Cloud with a GitHub App, enable Deploy automatically on push. Deleting a target removes its values; its runs are kept.

Saving the form persists every valid field immediately and reports invalid ones inline with the submitted text kept in place, so a typo in one field never costs you the other forty-nine.

Renaming a target

A target’s name is a label; its identity is a stable ID. Renaming changes what runs see as KEEL_TARGET (and the target’s URL), so the settings form asks for confirmation. It does not change KEEL_TARGET_ID, and it cannot move state that lives outside Keel — so deployments should key anything persistent (a Terraform state key, a stack name) by KEEL_TARGET_ID, which survives the rename. See the run environment.

Runs

A run is one execution of a deployment against a target. Runs are created by the Deploy button, by keel deploy, or — in Keel Cloud with a GitHub App — by a push to the connected branch.

Starting a run

If the deployment has deploy-time variables, Deploy now opens a modal that asks for them, pre-filled with defaults; a required deploy-time value that is missing or invalid blocks the deploy with an inline error. Without deploy-time variables the button starts the run immediately.

Before anything executes Keel validates the full merged set of values — saved configuration plus deploy-time values — and refuses to start if a value is missing or invalid, listing the problems on the target page. It also checks that Docker is reachable. In Keel Cloud, a target can have only one active run at a time.

Inputs

Every run records the values it was started with, so a run stays explainable long after the target’s variables or keel.yaml have changed. The run page shows them in two groups: the values chosen when the deploy started (deploy-time variables — the plan/apply switch, the image tag) and the target’s configuration at that moment, each with the label it had then and a note when the value came from a default, was not set, or was inactive because its condition did not hold. Run tables show the deploy-time choices as chips (ACTION=destroy) so history can be scanned.

Secret inputs are recorded as set, never as values — unlike secret outputs, which are meant to be read back, a secret input is never shown again once saved. Non-secret values are encrypted at rest like target values.

Lifecycle

Status	Meaning
queued	Created, waiting to start.
building	The environment image is being built.
running	Steps are executing.
succeeded	Every step exited zero; outputs were captured.
failed	A step exited non-zero, the build failed, or the server restarted mid-run.
canceled	Stopped on request; the container was removed.

Each step has its own status — pending, running, succeeded, failed, or skipped — shown next to the log.

Logs

Logs stream live to the run page over server-sent events and are persisted, so a run’s log can be read later and the page can be reloaded mid-run. Secret values are replaced with ••• before a line is stored or shown.

A single log line longer than 1 MB cannot be processed; Keel notes it in the log and discards the rest of that output stream for the remainder of the run, which otherwise continues.

Canceling

Cancel force-removes the run’s container. The run is marked canceled, the current step failed, and later steps skipped. Whatever the steps had already done in the target system stays done — Keel does not roll back.

Outputs

When every step succeeds, the declared outputs are read from the container’s final environment and stored with the run. They show on the run page and, for the latest successful run, on the target page. See Outputs.