dbt observability layer

Hightouch provides two separate features to monitor your dbt models as they relate to Hightouch syncs:

• dbt CI checks
• dbt exposure sync

You can use either one or both of these features together. Both require that you've set up dbt-based models in Hightouch.

dbt CI checks

You can use Hightouch's dbt CI checks to validate changes in your dbt project Git repository. This feature checks your GitHub pull requests to ensure they don't break any existing, enabled dbt-based syncs in Hightouch.

To enable this, toggle on GitHub Pull Request checks from your dbt connected source's configuration page and then select Save. You need to do this for every connected source you want to enable CI checking on.

Once enabled, Hightouch runs a CI check on any pull request made to the dbt project's Git repository. If a breaking change is detected—for example, deleting, renaming, or moving a model used in a sync—the check fails.

Clicking into the details of a failed CI check shows which sync the breaking change effects.

The CI check passes if the pull request doesn't affect any enabled Hightouch syncs.

dbt exposure sync

Hightouch exposure sync lets you see which Hightouch syncs are using your dbt models via your dbt docs and lineage graph.

Exposure sync works by defining and updating exposures in your chosen dbt repository anytime a Hightouch sync that uses a dbt model is added or modified.

Turn on exposure sync

You can enable exposure sync by navigating to dbt Models on the Extensions page and selecting your dbt Connected Source. From there, activate the dbt Exposures Sync toggle and click Save.

You should see exposures starting to sync within a few minutes.

In your dbt repository, you should see a new file called hightouch_sync_exposures.yml. This file updates every time a Hightouch sync that uses a dbt model is added, modified or disabled.

Tips and troubleshooting

Git credentials

If your Git credentials are out of date, you won't be able to connect your dbt models and analyses. We recommend using Hightouch's GitHub app for your credentials if you're using GitHub.

The Hightouch GitHub app must have commit access to your chosen dbt branch to create exposures. If Hightouch is unable to push to your branch you may have to update your branch protection rules in your dbt GitHub repository.

dbt build errors

The Hightouch exposures file is intended to stop you from breaking Hightouch syncs as a result of deleted dbt models. If you need to delete a model defined in the Hightouch exposures file, you can remove the Hightouch exposures file at any point—Hightouch will automatically recreate it.

Your local changes to the following files would be overwritten by checkout

This error generally occurs if the exposure sync branch in your linked Git repository has diverged from your main branch.

Once you update your exposure branch so that it's up-to-date with your main one, it should resolve the error. You can find more information on how you can resolve this type of error in this Stack Overflow article.

Remote rejected, protected branch hook declined

You may receive this error if you have branch protections on the branch you selected for you exposure sync configuration. To avoid this, you can select a branch to use for exposure syncs specifically.

Then, you can open a pull request from the dbt exposure sync branch to your main dbt branch. This allows the exposure sync with Hightouch to operate smoothly while also allowing branch protection rules to be applied to the main branch.