Git for Sigma

Manage Sigma data models as code. This repo provides two tools:

1. VS Code Extension — pull data models from Sigma into your repository.
2. GitHub Action — automatically sync data model changes pushed to main back to Sigma

Use Case 1: VS Code Extension

The extension lets you pull Sigma data models into your repository as YAML files, organized to mirror your Sigma workspace and folder structure. You can create, move, rename and delete folders and data models in your local file system..

Installation

The extension is not published to the VS Code Marketplace. Install it as a local extension or load it in development mode.

Development mode (for contributors):

1. Clone this repo and open the sigma_vscode folder in VS Code.
2. Run npm install.
3. Press F5 to launch an Extension Development Host window.

Packaged install:

npm install -g @vscode/vsce
vsce package
code --install-extension sigma-vscode-extension-*.vsix

Setup

Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and run:

Sigma: Configure API Credentials

Enter your:

• Sigma API URL (e.g. https://api.sigmacomputing.com)
• Sigma API Client ID
• Sigma API Secret

Credentials are stored in VS Code's Secret Storage — never in your repo.

Pulling data models from Sigma

Run Sigma: Sync Data Models from Sigma from the Command Palette.

This will:

• Fetch your Sigma workspace and folder structure
• Create a data-models/ directory in your workspace mirroring that structure
• Download each data model as a YAML file
• Add a .sigma-folder.json metadata file in each folder (stores the Sigma folder ID)

The folder structure and file names match what you see in Sigma.

Checking sync health

Sync state is tracked in .sigma/sync-state-<DATE>.json, where one json file is created for each day. The sync-state files are committed to your repo and used for recovery.

Use Case 2: GitHub Action (sync git → Sigma)

When changes to data-models/ are pushed to main, the action syncs those changes to Sigma.

Setup

Step 1: Copy the workflow files into your repo

Create a github action workflow from action.yml.

Step 2: Copy the extension code into your repo

The workflow scripts depend on the sigma_vscode directory. Copy the entire sigma_vscode/ folder (including src/, scripts/, and package.json) into your repo root.

Step 3: Add credentials to your repo

In your GitHub repo, go to Settings → Secrets and variables → Actions and add:

How the workflows trigger

data-model-workflow.yml — runs on every push to main that changes a file under data-models/:

• Skipped if the commit message contains [skip ci]
• Syncs added, modified, deleted, and moved data models and folders to Sigma
• Uploads .sigma/sync-state.json as a workflow artifact for debugging

Running the sync scripts locally

Both scripts can be run outside of GitHub Actions with environment variables:

export SIGMA_API_URL=https://api.sigmacomputing.com
export SIGMA_API_CLIENT_ID=<your-client-id>
export SIGMA_API_SECRET=<your-secret>

# Sync a specific commit to Sigma
node sigma_vscode/scripts/push-commit-to-sigma-cli.js <commitHash>

# Apply a tag to data models in Sigma
node sigma_vscode/scripts/tag-data-models-cli.js <tagName>

Repository layout

sigma_vscode/
  src/
    extension.js        # Extension entry point and command registration
    api/                # Sigma API clients
    commands/           # VS Code command handlers
    git/                # Commit-to-Sigma sync logic
    services/           # Folder sync, data model sync, file watcher
    config/             # Source mapping config manager
    utils/              # Auth, caching, sync state, error handling
  scripts/
    push-commit-to-sigma-cli.js   # CLI entry for data model sync
    ci-context.js                 # Maps env vars to VS Code context for CI

git/
  workflows/
    data-model-workflow.yml
    tag-workflow.yml

Key files created in your repo by the extension: