Docs / Core Concepts / Configuration & Deployment

Configuration & Deployment

Learn how to configure your project, define build pipelines, and deploy to production using the .git CLI and configuration files.

ℹ️ Prerequisite

Ensure you have .git-cli@2.4.1 installed and authenticated via git auth login.

Installation

Install the core CLI tool using your preferred package manager:

bash

npm install -g @git/cli
brew install git-tap/git/cli
cargo install git-cli

Project Configuration

All project settings are managed through .gitconfig.yml at your repository root. This file defines build commands, deploy targets, and environment matrixes.

yaml

version: 2
project: my-app
regions: [us-east-1, eu-west-1]

build:
  command: npm run build
  output: ./dist
  cache:
    - node_modules
    - .next/cache

deploy:
  preview:
    branch: develop
    timeout: 300s
  production:
    branch: main
    canary: true
    rollback: auto

env:
  NODE_ENV: production
  LOG_LEVEL: warn

Environment Variables

Secrets and environment configurations can be injected via the dashboard or CLI. They are scoped by environment and region.

Variable	Type	Description	Default
`GIT_DEPLOY_TOKEN`	Secret	Authentication token for deployment endpoints	Required
`GIT_REGION`	String	Target edge region for routing	auto
`GIT_MAX_RETRIES`	Integer	Deployment failure retry limit	3
`GIT_HEALTHCHECK_PATH`	String	Endpoint verified post-deployment	/health

Deployment Commands

The CLI supports intelligent deployments with automatic preview environments, canary releases, and instant rollbacks.

bash

# Deploy to preview environment
git deploy --env preview --region us-east-1

# Trigger canary release (10% traffic)
git deploy prod --canary 10% --wait

# Force rollback to previous stable build
git rollback --target v2.3.8-rc1 --force

⚠️ Traffic Shifting

Canary deployments automatically shift traffic in 5% increments every 2 minutes if error rates remain below 0.1%. Manual intervention pauses auto-shifting.

Common Errors

If your deployment fails, check the following:

EAUTH_FAILED: Your deployment token is expired or lacks deploy:write scope.
EBUILD_TIMEOUT: Build process exceeded 300s limit. Optimize cache or increase timeout in config.
ENET_HEALTH: Healthcheck endpoint returned non-2xx status post-deploy.

🚫 Critical

Never commit GIT_DEPLOY_TOKEN to version control. Use git secrets or your VCS's native secret scanning to prevent leaks.