Git-backed Models

See and make changes to Census SQL models via YAML files in your Git repositories.
Git-backed Models is only accessible to Platform Plan accounts. If you would like to enable version control and are not on the Platform Plan, please contact us at [email protected].
Git-backed Models enables you to leverage best practices of production software development – like peer review and version control – when making changes to your Census workspace. This gives you:
Resources as Code: Specify your Census SQL models in YAML configuration files.
Bi-directional Updates: Make changes to Census via the Census UI, or by updating the YAML configuration files in your Git repository.
Git-Backed Change History: View and rollback changes to Census SQL models not just within the Census UI, but also within Git.
Creating, editing, and deleting SQL Models in the Census UI will back them up into a Git repository as YAML configuration files. All changes will be represented as commits to those files. 
A sample YAML configuration file within Git that describes a Census SQL model.
When you create and edit the configuration files via commits and pull requests in a Git repository, Census will materialize your changes into your Census workspace. 
Changes will also show their source (Census or Git). And don't worry, we still think YAML is great! Woohoo!
This will also enable a global History view of all SQL Model changes across your entire Census workspace. You can isolate exactly when those changes went into effect, and the latest Git commit associated with that change.
A sample set of changes within the new History view.
​
Setup
To set up Git-backed Models:
1.Go to Settings -> Integrations.
2.Click Setup.
3.You're now on the Git-backed Models configuration page. Let's get set up by connecting to Git: 
4.Select the repositories you would like to use for version control:
5.Once you select what repositories you want to be connected, it will redirect you back to the Git-backed Models configuration page. Select the specific repository and branch name that you'd like to use for version control.
Optionally, in addition to the repository and branch, you can select a directory where Census will read and write configuration files. Census will never edit any files outside of this path.
6.Once the repository, branch, and directory are saved, click Enable Git Sync. You'll see a modal pop up. Here, you can specify whether to use Census as the basis for the first sync (thus overriding all Census configuration files within Git), or to import Git configurations into Census (thus overriding all models within Census). Click Setup Git Sync to continue.
7.Click Setup Git Sync to continue. At this point, Census will be hard at work setting up Git-backed Models, synchronizing the state of Census and Git. This should take a few minutes.
8.Once the initial sync is done, Git-backed Models will be set up!
​
After Setup
Once Git-backed Models is enabled, users can continue to use Census as usual, with no changes to any workflows. Census will automatically commit all edits made within the UI to Git, without requiring any additional effort from users. Likewise, all changes within Git will automatically be synced to Census.
In addition, several new features will be available to users after the feature is enabled.
History View
Census provides a History View of all changes applied from Census to Git, and from Git to Census. To find the History View:
1.Navigate to the Integrations page and click View History.
2.You can see a full list of all changes, including the latest commit from the changes that were applied, the number of changes (and failures), and when the changes were applied.
Linked Git Configuration
Every resource within Census that is backed by version control will have a link to the YAML configuration file for that specific resource, and for the latest commit that introduced a change. You can find the link within the Census UI, for example within the Models page:
​
Troubleshooting
There are a few strict requirements in order to use Git-backed Models:
Because Git-backed Models keeps the state of Census and Git synchronized, Census must write to Git on each model save, and requires direct write-access to the specified branch and repository. This may conflict with certain branches that have branch protection (i.e. main). To fix this, you can add the Census Git app to the list of actors that bypass required pull request approvals once you install the app during the Setup flow.
The governed Git-backed Model directory (by default, census/models/*.sql) must be entirely empty, or populated only by configuration files that Census can read. As such, if you have .txt files, README.md files, or other files that are not YAML-deserializable and correspond to a known resource configuration by Census, Git-backed Models will not work.
Each SQL model should be in its own file.