Git Workflow for Xano Projects

This guide covers version control best practices for Xano projects using Xano Tools.

Overview
Initial Setup
Repository Generation
Branching Strategy
Daily Workflow
CI/CD Integration
Best Practices

Overview

Xano Tools enables Git-based version control for your Xano backend by:

Exporting workspace schema - Database structure, API definitions
Extracting XanoScript - Human-readable function code
Generating documentation - OpenAPI specs, API docs
Supporting automation - CI/CD pipelines

Initial Setup

1. Install and Initialize CLI

Bash

# Install globally
npm install -g @calycode/cli

# Initialize with your Xano instance
caly-xano init

# Follow prompts to configure:
# - Instance name
# - Xano URL
# - Metadata API token
# - Output directory

2. Generate Initial Repository

Bash

# Generate complete repository structure
caly-xano generate repo \
  --instance production \
  --workspace main \
  --branch live

# Initialize Git
cd your-project-directory
git init
git add .
git commit -m "Initial Xano workspace export"

3. Set Up Remote

Bash

# Add remote repository
git remote add origin https://github.com/your-org/xano-backend.git
git push -u origin main

Repository Generation

The `generate repo` Command

Bash

caly-xano generate repo [options]

Options:

Option	Description
`--instance <name>`	Xano instance name
`--workspace <name>`	Workspace name
`--branch <name>`	Xano branch
`--output <dir>`	Output directory
`--fetch`	Force fresh fetch from Xano
`--print-output-dir`	Print output path

Generated Structure

Code

project/
├── schema/
│   └── workspace-schema.json    # Full workspace schema
├── xanoscript/
│   ├── functions/               # Function stacks
│   ├── apis/                    # API groups and endpoints
│   ├── tables/                  # Table definitions
│   ├── addons/                  # Addons
│   ├── tasks/                   # Scheduled tasks
│   ├── middleware/              # Middleware
│   └── triggers/                # Triggers
├── openapi/
│   └── spec.json                # OpenAPI specification
└── docs/
    └── api-docs.html            # Generated documentation

XanoScript Extraction

For just XanoScript (lighter weight):

Bash

caly-xano generate xanoscript \
  --instance production \
  --workspace main \
  --branch live

Branching Strategy

Recommended Model

Code

main (production)
│
├── staging (pre-production)
│
├── develop (integration)
│   ├── feature/user-auth
│   ├── feature/api-v2
│   └── feature/payment
│
└── hotfix/critical-fix

Branch Mapping

Map Git branches to Xano branches:

Git Branch	Xano Branch	Purpose
`main`	`live`	Production
`staging`	`staging`	Pre-production testing
`develop`	`develop`	Integration
`feature/*`	`dev` or feature branches	Development

Creating Feature Branches

Bash

# Create Git branch
git checkout -b feature/new-api

# Work in corresponding Xano branch
# (Use Calycode Extension for branch management)

# Export changes
caly-xano generate xanoscript --branch dev

# Commit
git add .
git commit -m "Add new API endpoints"

Daily Workflow

Morning Sync

Bash

# Pull latest changes
git pull origin develop

# Check for updates from Xano
caly-xano generate xanoscript --branch develop

# Review changes
git status
git diff

After Making Changes in Xano

Bash

# Export your changes
caly-xano generate repo --branch develop

# Review what changed
git status
git diff

# Commit with descriptive message
git add .
git commit -m "feat: add user profile endpoint

- Added GET /users/profile endpoint
- Added update profile functionality
- Added validation for profile fields"

# Push to remote
git push origin feature/user-profile

Before Merging

Bash

# Run tests
caly-xano test run -c ./tests/config.json --branch develop --ci

# Generate fresh docs
caly-xano generate docs

# Final export
caly-xano generate repo --branch develop

# Commit any doc changes
git add .
git commit -m "docs: update API documentation"

CI/CD Integration

GitHub Actions Example

YAML

# .github/workflows/xano-sync.yml
name: Xano Sync

on:
   schedule:
      - cron: '0 */6 * * *' # Every 6 hours
   workflow_dispatch: # Manual trigger

jobs:
   sync:
      runs-on: ubuntu-latest
      steps:
         - uses: actions/checkout@v4

         - name: Setup Node.js
           uses: actions/setup-node@v4
           with:
              node-version: '20'

         - name: Install Xano CLI
           run: npm install -g @calycode/cli

         - name: Generate Repository
           env:
              XANO_TOKEN_PRODUCTION: ${{ secrets.XANO_TOKEN }}
           run: |
              caly-xano generate repo \
                --instance production \
                --workspace main \
                --branch live \
                --fetch

         - name: Check for Changes
           id: changes
           run: |
              if [[ -n $(git status --porcelain) ]]; then
                echo "has_changes=true" >> $GITHUB_OUTPUT
              fi

         - name: Commit Changes
           if: steps.changes.outputs.has_changes == 'true'
           run: |
              git config user.name "GitHub Actions"
              git config user.email "[email protected]"
              git add .
              git commit -m "sync: update from Xano production"
              git push

Test on Pull Request

YAML

# .github/workflows/test.yml
name: API Tests

on:
   pull_request:
      branches: [main, develop]

jobs:
   test:
      runs-on: ubuntu-latest
      steps:
         - uses: actions/checkout@v4

         - uses: actions/setup-node@v4
           with:
              node-version: '20'

         - name: Install Xano CLI
           run: npm install -g @calycode/cli

         - name: Run Tests
           env:
              XANO_TOKEN_STAGING: ${{ secrets.XANO_TOKEN_STAGING }}
              XANO_TEST_EMAIL: ${{ secrets.TEST_EMAIL }}
              XANO_TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
           run: |
              caly-xano test run \
                -c ./tests/config.json \
                --instance staging \
                --workspace main \
                --branch staging \
                --all \
                --ci

Documentation Deployment

YAML

# .github/workflows/docs.yml
name: Deploy Docs

on:
   push:
      branches: [main]

jobs:
   deploy:
      runs-on: ubuntu-latest
      steps:
         - uses: actions/checkout@v4

         - uses: actions/setup-node@v4
           with:
              node-version: '20'

         - name: Install Xano CLI
           run: npm install -g @calycode/cli

         - name: Generate Documentation
           env:
              XANO_TOKEN_PRODUCTION: ${{ secrets.XANO_TOKEN }}
           run: caly-xano generate docs

         - name: Deploy to GitHub Pages
           uses: peaceiris/actions-gh-pages@v3
           with:
              github_token: ${{ secrets.GITHUB_TOKEN }}
              publish_dir: ./docs

Best Practices

Commit Messages

Follow conventional commits:

Code

type(scope): description

Types:
- feat: New feature
- fix: Bug fix
- docs: Documentation
- refactor: Code refactoring
- test: Tests
- sync: Xano sync

Examples:
- feat(api): add user authentication endpoints
- fix(auth): correct token expiration handling
- docs: update API documentation
- sync: update from Xano production

What to Commit

Do commit:

XanoScript files (.xs)
Schema exports (JSON)
OpenAPI specifications
Documentation
Test configurations
CI/CD workflows

Don't commit:

Secrets or API tokens
Environment-specific configurations
Temporary files
Build artifacts

.gitignore

gitignore

# Environment
.env
.env.*

# Secrets
**/secrets/
*.secret

# Build
node_modules/
dist/

# Temporary
*.tmp
*.log

# IDE
.vscode/
.idea/

Environment Variables

Store tokens securely:

Bash

# Local development (.env - not committed)
XANO_TOKEN_PRODUCTION=your-token-here
XANO_TOKEN_STAGING=your-staging-token

# CI/CD - use secrets management
# GitHub: Settings > Secrets > Actions
# GitLab: Settings > CI/CD > Variables

Code Review Checklist

Before merging:

XanoScript exported and committed
Tests pass (caly-xano test run --ci)
Documentation updated
No secrets in code
Follows naming conventions
Dependencies documented

Troubleshooting

Common Issues

Issue	Solution
"Instance not found"	Run `caly-xano init` to configure
"Authentication failed"	Check `XANO_TOKEN_*` env vars
Merge conflicts in JSON	Regenerate from Xano, resolve manually
Missing XanoScript	Ensure Xano 2.0+ for XanoScript support

Regenerating After Conflicts

Bash

# Discard local changes
git checkout -- .

# Fresh export from Xano
caly-xano generate repo --fetch

# Review and commit
git add .
git commit -m "sync: regenerate from Xano"

Git Workflow for Xano Projects

Table of Contents

Overview

Initial Setup

1. Install and Initialize CLI

2. Generate Initial Repository

3. Set Up Remote

Repository Generation

The `generate repo` Command

Generated Structure

XanoScript Extraction

Branching Strategy

Recommended Model

Branch Mapping

Creating Feature Branches

Daily Workflow

Morning Sync

After Making Changes in Xano

Before Merging

CI/CD Integration

GitHub Actions Example

Test on Pull Request

Documentation Deployment

Best Practices

Commit Messages

What to Commit

.gitignore

Environment Variables

Code Review Checklist

Troubleshooting

Common Issues

Regenerating After Conflicts

Resources

Git Workflow for Xano Projects

Table of Contents

Overview

Initial Setup

1. Install and Initialize CLI

2. Generate Initial Repository

3. Set Up Remote

Repository Generation

The generate repo Command

Generated Structure

XanoScript Extraction

Branching Strategy

Recommended Model

Branch Mapping

Creating Feature Branches

Daily Workflow

Morning Sync

After Making Changes in Xano

Before Merging

CI/CD Integration

GitHub Actions Example

Test on Pull Request

Documentation Deployment

Best Practices

Commit Messages

What to Commit

.gitignore

Environment Variables

Code Review Checklist

Troubleshooting

Common Issues

Regenerating After Conflicts

Resources

The `generate repo` Command