---
title: "Configuration"
description: "The complete orbit.yaml reference: environments as overlays, health checks, secrets."
canonical: "https://orbit-handbook.sitesmojo.com/docs/configuration/"
---

# Configuration

Everything Orbit knows about your service lives in one file: `orbit.yaml`,
checked into the repository root. No dashboard state, no hidden settings -
review a deploy change the way you review code.

## A complete example

```yaml
app: hello-api
build: docker            # docker | buildpack | static
environments:
  staging:
    url: https://staging.hello.example
    replicas: 1
  production:
    url: https://hello.example
    replicas: 3
    protect: true        # always ask before applying
health:
  path: /healthz
  timeout: 5s
release:
  keep: 10               # releases retained for rollback
  strategy: bluegreen    # bluegreen | rolling
```

## Top-level keys

| Key | Required | What it does |
|-----|----------|--------------|
| `app` | yes | Name; must be unique within your org |
| `build` | yes | How the artifact is produced |
| `environments` | yes | Named overlays - anything set here overrides the top level |
| `health` | no | Endpoint Orbit polls before traffic moves |
| `release` | no | Retention and rollout strategy |

## Environments are overlays

An environment only states what *differs*. Everything else is inherited from
the top level, which is why staging and production cannot silently drift:
the diff between them is visible in one file.

## Secrets

Secrets never go in `orbit.yaml`. Reference them; Orbit resolves at apply
time from your secret store:

```yaml
env:
  DATABASE_URL: ${secret:hello-api/database-url}
```

A plan shows *that* a secret changed, never its value.