Application manifest - Towbar

An app is one service declared under .towbar/apps/*.app.yml. Its file defines common settings and an environments map; towbar.yml declares which environment names exist. Towbar reads the committed file at the mapped branch and validates the effective configuration before deploying.

.towbar/apps/web.app.yml

id: web
name: Web
deployment:
  type: dockerfile
  context: .
  dockerfile: Dockerfile
container:
  port: 3000
health:
  path: /health
environments:
  production:
    server: 192.0.2.10

Register the example IP under Servers and map production to a branch before syncing.

Field map

Field	Purpose	Guide
`id`, `name`, `description`	Durable identity and display text. Keep `id` stable across file moves and renames.	App overview
`deployment`	Dockerfile, static, OCI image, Railpack, Nixpacks, or Buildpacks.	Deployment modes
`server`, `environments`	Target server and per-environment overrides.	Environment branches
`container`, `health`	Process port, resources, networking, storage, and readiness.	Container and health
`domains`, `ingress`, `tls`	Public routing and certificate policy.	Routing and TLS
`secrets`, `externalSecrets`	Required keys and an external-secret source; values stay outside Git.	Towbar secrets, external secrets
`autoDeploy`, `preview`, `notifications`, `vulnerabilityScanning`	Automation, previews, subscriptions, and scanning.	Automation and previews
`jobs`, `hooks`	Scheduled commands and deployment-stage commands.	Scheduled jobs, deployment hooks
`rollout`, `buildServer`	Replacement strategy and optional separate builder host.	Deployment modes

context and dockerfile can also appear as compatibility fields on older app files; put new build settings under deployment. The exact accepted shapes and constraints are in the app JSON Schema. Repository sync also checks cross-workload conditions such as server registration and conflicting network aliases.

Common and environment values

Put shared settings at the top level and override allowed fields under an environment. Objects merge recursively, while an environment array replaces the common array. Identity, secret declarations, and preview configuration stay at entity level. A failed sync does not partially replace the last valid app configuration or its stored secret values.

Last modified on September 26, 2026