Git Repository Setup

Convert your local nao project into a Git repository for version control, collaboration, and automated deployments.

Once your context lives in a GitHub repository, you can also connect it to nao chat so context admins can edit context files and open pull requests from the browser. See Git.

Why Use Git?

Using Git for your nao project provides:

Version Control: Track changes to your context files
Collaboration: Multiple team members can contribute
Automated Sync: Use GitHub Actions to automatically sync context
Deployment: Easy integration with cloud deployments (Cloud Run, etc.)
Backup: Your context is safely stored in the cloud

Initial Setup

Step 1: Initialize Git Repository

Navigate to your nao project directory:

cd your-nao-project

Initialize a Git repository:

git init

Step 2: Create .gitignore

Create a .gitignore file to exclude sensitive files:

# Environment variables
.env

# Credentials (never commit these!)
credentials/

# Python
venv/

Never commit credentials or API keys to Git! Always use environment variables or secret management systems.

Step 3: Configure for Git

Update your nao_config.yaml to use environment variables instead of file paths: Before (local files):

databases:
  - name: bigquery-prod
    type: bigquery
    project_id: my-project
    dataset_id: analytics
    credentials_path: /path/to/credentials/key-file.json

After (environment variables):

databases:
  - name: bigquery-prod
    type: bigquery
    project_id: my-project
    dataset_id: analytics
    credentials_json: {{ env('GCP_SERVICE_ACCOUNT_KEY_JSON') }}

Step 4: Add and Commit Files

Add your project files:

git add .
git commit -m "Initial nao project"

Step 5: Create GitHub Repository

Go to GitHub and create a new repository
Don’t initialize with README, .gitignore, or license (you already have these)
Copy the repository URL

Step 6: Connect to GitHub

Add the remote and push:

git remote add origin https://github.com/your-username/your-repo.git
git branch -M main
git push -u origin main

Best Practices

1. Use Environment Variables Always use environment variables for secrets:

# ✅ Good
credentials_json: {{ env('GCP_SERVICE_ACCOUNT_KEY_JSON') }}
api_key: ${OPENAI_API_KEY}

# ❌ Bad - Never do this
credentials_path: ./credentials/key.json
api_key: sk-abc123...

2. Store Secrets Securely For Local Development:

Use .env file (in .gitignore)
Load with source .env or a tool like direnv

For Cloud Deployments:

Use secret management (Google Secret Manager, AWS Secrets Manager, etc.)
Store in GitHub Secrets for Actions

For GitHub Actions:

Go to repository Settings → Secrets and variables → Actions
Add secrets for all credentials used in nao_config.yaml

3. Commit Synced Context After running nao sync, commit the generated context files:

nao sync
git add databases/ docs/ repos/
git commit -m "Update context from nao sync"
git push

4. Use Automated Sync Set up GitHub Actions to automatically sync and commit context updates.

Deployment Integration

Cloud Run Deployment When deploying to Cloud Run:

Connect your GitHub repository to Cloud Build
Cloud Build automatically builds and deploys on push
Use Secret Manager for credentials
Environment variables are set in Cloud Run configuration

See the Self-Hosting Guide for Cloud Run deployment details. Dockerfile Create a Dockerfile in your repository:

FROM getnao/nao:latest

# Copy your project
COPY . /app/project/

# Set working directory
WORKDIR /app/project

Create a .dockerignore:

.env
venv/
.git/
.gitignore
credentials/

Scheduling with GitHub Actions

Set up automated syncing with GitHub Actions to keep your context up to date. This runs nao sync on GitHub’s servers on a schedule, commits any changes to your context files (like updated database schemas or docs), and pushes them back so your context stays current without manual commands. 1. Create Workflow File Create .github/workflows/nao-sync.yml in your repository:

name: Nao Sync

on:
  schedule:
    - cron: "0 0 */2 * *"  # every 2 days at 00:00 UTC
  workflow_dispatch:  # allows manual triggering

jobs:
  nao-sync:
    runs-on: ubuntu-latest
    permissions:
      contents: write  # needed to commit changes

    env:
      NAO_CONFIG_PATH: ./nao_config.yaml

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          ref: ${{ github.ref }}

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install Nao CLI
        run: |
          pip install --upgrade pip
          pip install nao-core
          pip install "ibis-framework[bigquery]"  # warehouse driver for your DB

      - name: Run nao sync
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GOOGLE_APPLICATION_CREDENTIALS_JSON: ${{ secrets.GCP_SERVICE_ACCOUNT_KEY_JSON }}
          # Add other secrets as needed (e.g., NOTION_API_KEY, etc.)
        run: nao sync

      - name: Configure Git
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"

      - name: Commit and push changes
        run: |
          git add -A
          if git diff --staged --quiet; then
            echo "No changes to commit"
          else
            git commit -m "nao sync update"
            git push origin HEAD:${{ github.ref_name }}
          fi

2. Configure Repository Secrets In your GitHub repository:

Go to Settings → Secrets and variables → Actions
Click “New repository secret”
Add secrets for all environment variables used in your nao_config.yaml:
- ANTHROPIC_API_KEY - Required for nao sync to run the agent
- GCP_SERVICE_ACCOUNT_KEY_JSON - Full JSON content of your BigQuery service account
- NOTION_API_KEY - If using Notion integration
- Any other credentials referenced in your config

Never commit secrets directly in your workflow file. Always use GitHub Secrets.

3. Customize Schedule Adjust the cron schedule to match your needs:

on:
  schedule:
    - cron: "0 0 * * *"      # Daily at midnight UTC
    - cron: "0 0 */2 * *"    # Every 2 days
    - cron: "0 0 * * 1"      # Weekly on Monday
    - cron: "0 3 * * *"      # Daily at 3 AM UTC

4. Manual Trigger You can manually trigger the sync:

Go to Actions tab in your repository
Select “Nao Sync” workflow
Click “Run workflow”

5. Monitor Sync Results

Check the Actions tab to see sync history
Review logs if sync fails
Verify changes are committed to your repository

The workflow automatically commits and pushes any changes from nao sync back to your repository, keeping your context files up to date.

What’s Next?

Configuration

Configure your project and run nao sync

Self-Hosting Guide

Deploy your repository to production (local Docker & Cloud Run)

Get Started

Context Builder

Context Engineering

Chat Interface

Connectors

Self-Hosting

nao Cloud

nao Enterprise

Developers

Git Repository Setup

Why Use Git?

Initial Setup

Step 1: Initialize Git Repository

Step 2: Create .gitignore

Step 3: Configure for Git

Step 4: Add and Commit Files

Step 5: Create GitHub Repository

Step 6: Connect to GitHub

Best Practices

Deployment Integration

Scheduling with GitHub Actions

Configuration

Self-Hosting Guide

​Why Use Git?

​Initial Setup

​Step 1: Initialize Git Repository

​Step 2: Create .gitignore

​Step 3: Configure for Git

​Step 4: Add and Commit Files

​Step 5: Create GitHub Repository

​Step 6: Connect to GitHub

​Best Practices

​Deployment Integration

​Scheduling with GitHub Actions

Configuration

Self-Hosting Guide

Why Use Git?

Initial Setup

Step 1: Initialize Git Repository

Step 2: Create .gitignore

Step 3: Configure for Git

Step 4: Add and Commit Files

Step 5: Create GitHub Repository

Step 6: Connect to GitHub

Best Practices

Deployment Integration

Scheduling with GitHub Actions