Configure Schema Git Sync

Schema Git Sync extends Git Sync, Hightouch’s integration for version-controlling resources in Git, to include Customer Studio schema models, events, and relationships. Use it to keep schemas consistent across environments (for example, staging and production) and to version, review, and recover changes directly from your Git repository.

Overview

Schema Git Sync connects your Customer Studio schema—parent, related, and event models, plus their relationships—to a Git repository.

Whenever you update your schema in Hightouch, the changes are automatically written to YAML files in Git, and vice versa.

This gives your team all the benefits of version control for your customer data model:

• Every schema change is captured as a Git commit.
• You can roll back to earlier versions if needed.
• Teams can review and approve schema updates using pull requests.
• Environments like staging and production can stay perfectly aligned.

Think of it as turning your schema into infrastructure as code: you define your data model in Hightouch, but track, share, and deploy it safely through Git.

For authentication, repository setup, and permissions, see the main Git Sync guide →.

Roles and responsibilities

Setup overview

Schema Git Sync setup involves these main steps:

1. Set up and enable Git Sync in your workspaces
2. Create your Git repository
3. Connect Git to each workspace
4. Configure branches and paths
5. Build your schema in Customer Studio
6. Sync schema changes to Git
7. Validate and troubleshoot syncs

For repository authentication and credential setup, see the main Git Sync guide →.

Step 1 – Set up workspaces

Create or identify the Hightouch workspaces you’ll connect to Git.

Each workspace typically represents an environment (for example, staging and production).

Step 2 – Create your Git repository

Create a dedicated Git repository for your schema files.

Hightouch uses this repo to store YAML definitions for all models, events, and relationships.

Recommended folder structure:

/syncs/                # YAML files for all syncs
/models/               # YAML files for all models
/schema/               # Customer Studio schema files
  ├── event-models/    # Event model definitions
  ├── related-models/  # Related model definitions
  ├── parent-models/   # Parent model definitions
  ├── model-relationships/ # Relationship model definitions
manifest-*.yaml         # Auto-generated source/destination listings

Step 3: Connect Git to each workspace

Configure your Git repository connection from Hightouch.

1. In Hightouch, go to Integrations → Extensions and select Version control with Git.

   

2. Under Overview, click Configure extension.

   

3. Under Git credentials, click Set up and select your Git service (e.g., GitHub App).
4. Follow the Git Sync Authentication instructions to authenticate and grant Hightouch permission to your repository.

   

   Once connected, Hightouch displays your sync status and automatically detects inbound and outbound changes.

Step 4: Configure file paths (branches)

Assign each workspace a unique file path name (branch or sub-path) in your repository to avoid conflicts.

Example mapping:

Step 5: Create your schema

Build your schema models in Customer Studio.

Define:

• Parent models (e.g., Users table)
• Related models (e.g., Purchases, Subscriptions)
• Event models (e.g., Page Views, Clicks)
• Relationships between models

Each model and relationship automatically becomes a YAML file in your Git repository under /schema/.

Example workflow:

1. Create a Users parent model.
2. Add a related model such as Purchases.
3. Define a relationship between them (e.g., “Users → Purchases”).
4. Save — Hightouch commits each definition as YAML in Git.

Step 6: Sync schema to Git

You can trigger an initial sync manually or wait for Hightouch to sync automatically after saving your schema.

You can view sync progress in the Runs tab of the Git Sync extension.

How syncing works

• Automatic commits: Each save in Customer Studio triggers a commit in Git.
• Two-phase commits: Models commit first, relationships second (to satisfy dependencies).
• Sync monitoring: Track commits in the Git Sync → Runs tab or by checking your repo history.
• Commit timing: Large schemas may take 10–20 minutes to finish syncing.

Step 7 - Two-phase commit process

Schema Git Sync automatically commits schema changes in two stages to prevent dependency errors.

This process happens automatically during both manual and automatic syncs.

Validation Checklist

Before running your first sync, verify the following:

• Git Sync feature flag is enabled for each workspace.
• All workspaces use identical model slugs.
• Each workspace includes an alias file (aliases-{workspace-slug}.yaml).
• Branches or paths are unique per workspace.
• Data sources are cloned consistently across environments.

Resource slug consistency and aliases

Hightouch uses resource slugs (unique identifiers) to connect schema definitions across workspaces.

When those slugs differ--such as when staging and production use different data sources--you can use alias files to bridge the difference.

How alias files work

Each workspace has its own alias file in the Git repository:

aliases-{workspace-slug}.yaml

Example:

sources:
  main-database: source-001
destinations:
  crm-platform: destination-002

Your schema YAML files then reference the alias names (for example, main-database, crm-platform) instead of the actual slugs. This lets you share the same schema across multiple environments.

For complete alias examples and behavior, see Aliases in Git Sync.

Troubleshooting

If a sync fails with an error like:

error serializing resource

Meaning

Git Sync tried to serialize (save) a schema component to YAML but couldn’t find a matching resource in the workspace.

Common causes

• Mismatched model or source slugs between environments
• Missing or incorrect alias mappings
• Workspace connected to the wrong Git branch
• Schema synced before alias setup

Fix checklist

1. Verify model and source slugs match across environments.
2. Confirm alias files map correctly to workspace resource IDs.
3. Ensure each workspace is using its correct Git branch.
4. Trigger a Full resync after correcting slugs or aliases.

For more help, see the Git Sync troubleshooting guide or contact Hightouch Support.

Multi-environment setup example

This structure allows both environments to share the same schema YAML files while maintaining different data-source mappings.

Best practices

• Plan workspace and branch structure before syncing.
• Test schema changes in staging before merging to production.
• Use pull requests to review schema changes before deployment.
• Keep model slugs consistent; use aliases for environment-specific differences.
• Periodically audit alias files and manifests after cloning or renaming resources.
• Document your branch-to-workspace mapping for future maintainers.

Related resources

• Git Sync Overview
• Schema management in Customer Studio
• Sync monitoring
• Warehouse sync logs