Initializing a Project

Learn how to set up a new repository, configure your workspace, and prepare your project for automated builds and deployments.

Prerequisites

Before initializing a project, ensure you have the following installed and configured:

Node.js 18+ or your runtime of choice
Git 2.30+ with standard credential helpers
A valid .git account with an active API token

ℹ️

Tip: You can manage API tokens via git config --global git.token or by editing your ~/.git/config file directly.

Step 1: Install the CLI

The .git CLI is required for project initialization and local automation. Install it using your preferred package manager:

bash

# npm
$ npm install -g @git/cli

# yarn
$ yarn global add @git/cli

# pnpm
$ pnpm add -g @git/cli

Step 2: Initialize your project

Navigate to your project directory and run the initialization command. The CLI will scan your workspace, detect frameworks, and generate the required configuration files.

bash

$ git init --project

✓ Detecting framework: Next.js 14.2
✓ Generating .git/config.yml
✓ Setting up branch protection rules
✓ Configuring preview deployments

Project successfully initialized.
Run git status to verify your setup.

Step 3: Configure .git/config.yml

By default, the CLI creates a basic configuration file. You can customize build commands, environments, and deployment targets.

yaml

# .git/config.yml
project:

  name: my-app
  framework: nextjs
  rootDir: ./src

build:

  command: npm run build
  outputDir: .next
  env: nodejs20

deploy:

  regions: [us-east-1, eu-west-2, ap-southeast-1]
  autoPreview: true
  ssl: true

Configuration Reference

Property	Type	Description
project.name Required	string	Unique identifier for your project in the dashboard
project.framework	string	Auto-detected. Override if using custom tooling
build.command	string	Shell command to compile your application
deploy.autoPreview	boolean	Generates ephemeral URLs for every PR branch

Step 4: First commit & push

Once configuration is complete, commit your changes and push to your remote repository. .git will automatically trigger your first pipeline.

bash

$ git add .
$ git commit -m "initial setup: add .git config and CI rules"
$ git push origin main

✓ Pushed to remote repository
✓ Pipeline #1024 triggered
  → View logs: https://git.dev/my-app/pipelines/1024

⚠️

Important: Do not commit sensitive credentials. Use git secrets or environment variables injected via the dashboard to handle API keys and database URLs.

Troubleshooting

If your initialization fails or the pipeline doesn't trigger automatically, run the diagnostic command:

bash

$ git doctor --verbose

Checking environment...
✓ CLI version up to date (2.4.1)
✓ Git credentials authenticated
✗ Missing required env var: NODE_ENV
Run git env set NODE_ENV production to fix.

← Introduction

Overview of the .git platform and architecture

Authentication →

Configure OAuth, API tokens, and team access