Manage Customer Studio schema with Git

Schema Git Sync stores Customer Studio models and relationships as YAML files in Git. Use it when your team wants to review schema changes through Git or keep the same schema configuration across environments such as staging and production.

Decide whether you need Schema Git Sync

You don't need Git Sync to use Customer Studio. You can create and manage your entire schema directly in Hightouch.

Use Schema Git Sync when your team needs one or more of these workflows:

• Review schema changes through pull requests.
• Test schema changes in staging before applying them to production.
• Keep the same schema structure across multiple Hightouch workspaces.
• Keep a versioned history of schema configuration in Git.

Set it up after you have a working schema in Customer Studio. This makes it easier to understand the files Git Sync creates and to confirm the same schema produces the expected models, relationships, and audience results in each environment.

Understand what Git Sync manages

Schema Git Sync stores these Customer Studio resources in Git:

• parent models
• related models
• event models
• relationships between models

When you make a supported change in Hightouch, Git Sync writes the updated configuration to YAML in your repository. Hightouch can also apply supported changes from Git to the workspace.

For example, a schema containing Users as a parent model, Purchases as a related model, Product Viewed as an event model, and the relationships connecting them is represented as separate YAML files in Git.

You don't need to create these files yourself. Create and configure the schema in Hightouch first, then use the generated YAML to review or edit configuration in Git. For YAML fields and supported configuration, see Customer Studio schema in Git Sync.

Choose how environments share schema configuration

If you use separate Hightouch workspaces for staging and production, decide whether they should share the same schema.

Use the same schema when staging and production should match

For most teams, staging and production should use the same parent models, related models, events, and relationships.

Point both workspaces at the same schema configuration when:

• they represent the same Customer Studio setup
• differences are limited to environment-specific sources or destinations
• you want to test a schema change before promoting it to production

The warehouse connections may differ between the two workspaces, but the Customer Studio schema stays the same. Git Sync maps the environment-specific sources and destinations with alias files.

Use separate configuration when the schemas are different

Use separate branches or paths when the schemas themselves should be different — for example, when your staging workspace contains an experimental parent model or relationship that you don't want production to read yet.

Don't create separate schema configuration just because staging and production point to different warehouse resources. Git Sync can map environment-specific sources and destinations without duplicating the schema.

Connect each workspace to Git

Configure Git Sync from Integrations > Extensions > Version control with Git.

If you haven't connected Git yet, follow the Git Sync setup guide to:

1. Authenticate to your Git provider.
2. Choose the repository.
3. Configure the branch and path the workspace should use.
4. Enable Git Sync.

You authenticate by choosing a Git service and connecting its app:

Then select the repository, branch, and optional path Hightouch should use:

Repeat this for each Hightouch workspace that should share schema configuration. Once connected, Hightouch creates the required Git Sync files and starts tracking supported resources.

Map environment-specific resources

Staging and production often use different warehouse sources or destinations — for example, a snowflake-dev source in staging and snowflake-prod in production. The Customer Studio schema can still stay identical.

Git Sync uses alias files to map each shared source or destination reference to the corresponding resource in each workspace. Hightouch creates one alias file per connected workspace, named for that workspace (for example, aliases-staging.yaml):

# aliases-staging.yaml
sources:
  main-database: snowflake-dev

# aliases-production.yaml
sources:
  main-database: snowflake-prod

Both environments use main-database in the shared schema configuration, and each alias maps it to the warehouse source for that workspace. Hightouch creates the alias file automatically. Edit the mappings only when equivalent resources have different identifiers between environments.

For a full multi-environment walkthrough, see Connect staging and production workspaces.

Sync your existing schema

When Schema Git Sync is enabled, Hightouch performs an initial sync of the supported schema configuration to Git. The generated repository includes files for your models and relationships under the schema directory.

After the initial sync, schema changes made in Customer Studio are written to Git automatically. You can monitor Git Sync from the Runs tab or inspect the resulting commits in your repository.

For large schemas, the initial sync can take longer than later incremental updates.

Review and apply schema changes

A schema change can affect existing audiences, traits, syncs, and journeys. Review which audiences, traits, syncs, and journeys the change could affect before you apply it to production.

A common workflow is:

1. Make the schema change in staging.
2. Build an audience that uses the changed model, field, or relationship.
3. Confirm the audience count and sample records match the expected results.
4. Review the generated Git changes.
5. Merge the change through your normal Git workflow.
6. Validate the same audience in production.

Enable Hightouch CI checks on the repository to catch breaking changes on a pull request — for example, deleting a model that a sync depends on — before the change merges.

Changes to validate before production

Revalidate dependent audiences, traits, syncs, and journeys when a change alters how existing data is identified or connected:

• changing what one row in a parent model represents
• changing a primary key
• removing or renaming a field used by audiences, traits, syncs, or journeys
• changing the fields used to connect two models
• changing whether a relationship is one-to-one or one-to-many
• deleting and recreating a relationship
• renaming a model or changing its identifier

Add replacement fields or relationships before removing existing ones when dependent assets still use them. For example, add a replacement field, update dependent audiences and traits to use it, then remove the old configuration after you confirm nothing still depends on it. Recreating a relationship generates a new internal ID, so review the model's Activity tab and rebuild a few affected audiences after relationship changes.

Configure settings that Git Sync doesn't store

Not every Customer Studio setting is stored in Git. After you apply structural schema changes to another workspace, review any workspace-specific settings affected by the change.

Depending on the change, you may need to:

• refresh available warehouse columns
• configure column privacy
• restore display names or descriptions
• configure filter suggestions
• set merge columns
• update traits or audiences that depend on changed fields
• validate any affected relationship paths

A successful Git Sync run confirms that Hightouch applied the stored schema configuration. It doesn't confirm that audiences, relationships, privacy settings, or field visibility work as expected.

Validate the schema in each environment

After your initial setup, or after promoting an important schema change, test the result in Customer Studio. At minimum:

• Confirm the expected parent, related, and event models appear.
• Confirm relationships connect the correct models and fields.
• Build an audience that uses the changed part of the schema.
• Compare the result with a warehouse query or the validated result from another environment.
• Confirm sensitive fields have the intended privacy settings.
• Test through relationships end to end if you use them.

For multi-environment setups, also confirm that each workspace maps to the intended warehouse source and destination.

Troubleshoot resource mapping errors

If Git Sync can't match a schema resource in Git to a resource in the Hightouch workspace, a run can fail with an error such as:

error serializing resource

This usually means Git Sync can't match one of the resources referenced by the configuration. Check:

1. Model identifiers — Shared models use the same identifiers in each workspace.
2. Aliases — Source and destination aliases point to resources that exist in the current workspace.
3. Branch or path — The workspace is reading the intended Git configuration.
4. Environment setup — Required sources and destinations exist before the schema references them.

After correcting the configuration, trigger a full resync. For additional errors, see the Git Sync troubleshooting guide.

Next steps

• Define your schema to create or update Customer Studio models and relationships.
• Git Sync to configure authentication, repository settings, and other version-controlled Hightouch resources.
• Connect staging and production workspaces for a multi-environment setup.