The objects you work with
A server can run instances from several Repositories and environments. Register the physical host once, then reference its IP address in entity files. Production and staging can use different servers or share a host while keeping separate containers, volumes, and secret values.
Configuration has three homes
Git describes the workload. The root file declares environments. Entity files define images or Dockerfiles, health checks, domains, resource limits, required secret keys, and deployment policy. Keep stable IDs when renaming an app or resource so its history stays attached. Towbar stores workspace state and workload secrets. Environment-to-branch mappings, SSH credentials and trust, concurrency, and encrypted workload secret values belong in Towbar. Saving a secret does not deploy it. The installation environment configures the control plane and integrations. Database credentials, service origins, internal authentication, provider credentials, notification routes, and static integration settings are configured on the host running Towbar. The dashboard lists only integrations whose complete environment configuration passed startup validation. GitHub installations and GitLab OAuth grants remain workspace state because they are created by provider authorization flows.A sync is different from a deployment
An environment sync reads one immutable commit from its mapped branch, validates the complete configuration, and updates its instances atomically. Invalid configuration leaves the previous instances and secret slots intact. It may queue automatic deployments when policy permits. A successful sync means the configuration was accepted; check the deployment separately to know whether it went live. A deployment records an immutable configuration snapshot. Secret values are resolved when execution starts. Health observations describe the running container and can change after a successful deployment.Production, staging, and previews
Map production tomain and staging to develop, for example, in Repository environment settings. Each environment reads its configuration from its own branch. Changing a mapping syncs configuration without automatically deploying or replacing the environment’s identity and data.
Previews run eligible same-repository pull requests targeting the branch mapped to a preview-enabled environment, with app opt-in also required. Preview secrets are isolated from the target environment’s persistent secrets. PR configuration does not change persistent instances or their required-secret slots, and previews do not clone database resources.
Continue with Your first deployment, or see the architecture for service and trust boundaries.