.git.yml Schema Reference

Complete documentation for the `.git.yml` configuration file that powers your deployments, builds, and environment management.

ℹ️

This schema follows Kubernetes-style resource definitions with GitOps conventions. All properties are case-sensitive. YAML and JSON formats are supported.

Root Configuration

The `.git.yml` file defines the primary resource configuration. Place it in your repository root.

Property	Type	Required	Default	Description
apiVersion	string	Required	—	Schema version. Must be `v2` or `v2-beta`.
kind	string	Required	Application	Resource type. Supported: `Application`, `Pipeline`, `Workflow`.
metadata	object	Required	—	Resource identity, labels, and annotations.
spec	object	Required	—	Desired state configuration for build, deploy, and runtime.
status	object	Read-Only	—	Current state populated by the .git controller. Do not edit.

spec.build

Controls the build lifecycle, artifact generation, and caching strategy.

runtime	string	Required	node20	Execution environment. Supported: `node18`, `node20`, `python3.11`, `go1.21`, `deno`.
commands	array[string]	Optional	[]	Shell commands executed in order. Access to `GIT_TOKEN` and `CACHE_DIR`.
cache	object	Optional	{ enabled: true }	Content-addressable build cache configuration.
timeout	integer	Optional	300	Maximum build duration in seconds.

spec.deploy

Defines deployment strategy, targets, and traffic routing rules.

strategy	enum	Required	rolling	`rolling` \| `blue-green` \| `canary` \| `recreate`
regions	array[string]	Optional	["us-east-1"]	Target edge regions for deployment.
rollback	object	Optional	{ auto: true }	Automatic rollback triggers on health check failure.
preview	object	Optional	{ enabled: false }	Ephemeral preview environments per pull request.

Complete Examples

# .git.yml - Full Application Configuration
apiVersion: v2
kind: Application
metadata:
  name: my-saas-app
  labels:
    team: platform
    tier: production
spec:
  build:
    runtime: node20
    commands:
      - npm ci --frozen-lockfile
      - npm run build
    cache:
      paths:
        - node_modules/
        - .next/cache/
    timeout: 600
  deploy:
    strategy: blue-green
    regions:
      - us-east-1
      - eu-west-1
    rollback:
      auto: true
      maxRestarts: 3
  environment:
    vars:
      NODE_ENV: production
      LOG_LEVEL: info
    secrets:
      - ref: vault/secrets/api-key
  scaling:
    min: 2
    max: 50
    targetCPU: 70
                    

Validation & Error Handling

The `.git` CLI validates your configuration against the JSON Schema before pushing. Common validation errors include:

SCHEMA_001 — Missing required field apiVersion
DEPLOY_003 — Invalid strategy enum value
SEC_012 — Secret reference format mismatch
NET_005 — Region not available in selected tier

🔍

Run .git validate --strict to catch schema drift and deprecated properties before deployment.