Configuration Reference

Complete guide to git.yaml and environment configuration for .git deployments.

v2.4.1 • Updated Dec 10, 2025

Overview

The git.yaml file is the primary configuration source for .git. It defines build commands, deployment targets, scaling rules, and monitoring behavior. The file must be placed in your repository root.

ℹ️

JSON format (git.json) is also supported. YAML is recommended for readability and inline comments.

File Structure

git.yaml

# .git config root
version: 2
app:
  name: my-service
  runtime: nodejs20
  port: 3000

build:
  command: npm run build
  cache: true
  timeout: 300 # seconds

deploy:
  regions: [us-east-1, eu-west-1, ap-south-1]
  auto_preview: true
  rollback: true

env:
  production:
    LOG_LEVEL: warn
    NODE_ENV: production

scaling:
  min_instances: 2
  max_instances: 50
  cpu_target: 70

Application Configuration

Defines runtime environment, entry points, and port binding.

Parameter	Type	Default	Required	Description
`app.name`	string	-	Required	Unique service identifier. Used in URLs and logs.
`app.runtime`	string	`auto-detect`	Optional	Runtime: `nodejs20`, `python3.11`, `go1.21`, `rust`, `docker`
`app.port`	integer	`8080`	Optional	Application listen port. Overridden by `$PORT` env var.
`app.entrypoint`	string	`index.js`	Optional	Custom entry file or command override.

Build Pipeline

Controls compilation, caching, and artifact generation.

Parameter	Type	Default	Required	Description
`build.command`	string	`npm run build`	Optional	Shell command executed during build phase.
`build.cache`	boolean	`true`	Optional	Enable layer caching for faster rebuilds.
`build.timeout`	integer	`180`	Optional	Max build duration in seconds.
`build.output_dir`	string	`dist/`	Optional	Directory containing production assets.

Deployment

Manages regional distribution, preview environments, and rollback behavior.

Parameter	Type	Default	Required	Description
`deploy.regions`	array	`["us-east-1"]`	Optional	Target edge regions. Supports `global` wildcard.
`deploy.auto_preview`	boolean	`false`	Optional	Create ephemeral URLs for pull requests.
`deploy.rollback`	boolean	`true`	Optional	Automatically revert on health check failure.
`deploy.canary_percent`	integer	`10`	Optional	Traffic percentage routed to new version initially.

Environment Variables

Sensitive values and runtime toggles. Managed via dashboard or config file.

⚠️

Never commit secrets to git.yaml. Use the .git dashboard or CI secrets manager.

Variable	Scope	Description
`.GIT_API_KEY`	Global	Authentication token for CLI and API access.
`.GIT_DEPLOY_TOKEN`	Write	Trigger deployments from external CI systems.
`.GIT_LOG_LEVEL`	Runtime	Override config file: `debug`, `info`, `warn`, `error`
`.GIT_SCALE_OVERRIDE`	Runtime	Temporarily pin instance count (e.g., `5`) for debugging.

Production Example

git.yaml

version: 2
app:
  name: payment-gateway
  runtime: go1.21
  health_check:
    path: /healthz
    interval: 15

deploy:
  regions: global
  canary_percent: 20
  rollback: true
  traffic_shaping: true

scaling:
  min_instances: 4
  max_instances: 100
  cpu_target: 65
  memory_target: 80

monitoring:
  metrics: true
  tracing: true
  logs:
    retention_days: 30
    destination: datadog

Precedence Rules

When configuration values conflict, .git resolves them in the following order (highest priority first):

CLI flags (git deploy --env production)
Environment variables (.GIT_*)
Dashboard overrides
git.yaml (repository root)
Organization defaults
Platform defaults