Git-Backed Modeling

Git-backed modeling is a way of working for larger organizations, where analysts, domain experts, engineers, and AI agents across several functions all work on the same data model. It is turned on per environment. Out of the box, a modeler builds and publishes straight from the app, and for one person or a small team that is usually all you need.

The case for it starts when a model has many hands on it. Metrics get redefined, new tables arrive, an edge case turns out to matter, and the people who notice first are rarely the engineers who maintain the model. When every change has to be handed to one team and wait its turn, the model falls behind, and people start working around it. When anyone can change it with no record, nobody trusts it.

Git-backed modeling lets the whole team change the model directly, with a record of every change and a chance to review it before it goes live. An analyst asks for a new metric in plain language. The agent makes the change in a draft. Whoever your team has chosen looks it over, or the author approves it themselves, and the update is published to every dashboard, agent, and data app that uses the model. Every published version shows who changed what and when.

How a Team Works on One Model

Each group does the part it is good at, and the model stays one governed thing.

• Engineers own the model and decide how changes get in. When the team wants a review step, every proposed change comes to them as something they can read line by line, already checked for errors, with the name of the person who asked for it.
• Analysts and domain experts ask for what should change, in plain language: a new metric, a corrected definition, a business rule the data alone cannot settle. The agent makes the change in a draft, and it goes through the same path as any other. No Malloy coding experience required to contribute.
• AI agents notice what people actually ask for and suggest improvements, such as a clearer description on a field or a view worth adding, as proposals for a person to approve rather than changes that land on their own.

What You Get

• Every change is a proposal. Work happens in a draft that belongs to the person who opened it. The draft has an author, a description of what it changes, and a record of every edit the agent made along the way. Nothing in it touches the published model until it is approved.
• You decide who approves. Approving a proposal is what publishes the new version, and your team decides who may approve. Require an engineer's sign-off on every change, or let the person who owns a model approve their own. Either way there is no side door: the published model only changes through an approved proposal, so what your dashboards and agents serve is always something a person signed off on.
• Changes are checked before they can land. The agent checks the model as it works, so a change that would break it is caught while it is being written. Reviewers see the result beside the proposal, and a failing change cannot be approved by accident.
• A complete history. Every published version records the proposal that produced it, who asked for it, and when. When a number on a dashboard changes, you can trace it to the change and the person behind it.
• Several people can work at once. If two people are changing the same model, the agent brings each draft up to date and shows what it took in. If two changes collide, the agent names the conflict and proposes a resolution for the author to confirm. If a change breaks the model, the agent fixes it in the same chat.
• Engineers review where they already work. Every proposal is also a pull request in GitHub, so engineers review, comment, and approve with the tools they already use. An engineer can also pull the branch down, make their own edits in their own editor, and push them back before approving. Nobody else has to open GitHub.

Hosted by Credible, or Your Own Repository

The repository is your choice. Credible can host one for you in its managed GitHub organization, so nobody on your team needs a GitHub account and your side of the setup is one toggle. Or bring your own repository and keep models next to the rest of your code.

Why It Is Different

Most analytics tools that connect to git make it an engineering project before anyone can start: accounts to create, permissions to grant, a repository to set up. Credible makes that a choice rather than a prerequisite. Take the hosted repository and setup is one toggle, or bring your own and get the same way of working on it.

Two things matter more. First, review is a real gate, not a permission. In most tools the only control is who may press publish, which answers "who may ship" but never "should this ship." Here a team can require a person's sign-off on every change, and a team that does not still gets the record and the checks. Second, the people asking for changes never touch the mechanics. The agent writes the code, keeps drafts current, resolves collisions, and fixes errors, so a domain expert improves a governed, versioned model with nothing but a sentence.

For Engineers: How It Works

Under the hood this is ordinary git, and that is the point. Once an environment is enrolled, every new draft package is backed by a git repository rather than by Credible's document store:

1. A draft is a branch. Asking the agent to build or edit a package cuts a branch from the repository's base branch (usually main). The package is a top-level directory in the repository; one repository serves the whole environment.
2. Every turn is a commit. As the agent edits, each turn lands as a commit attributed to the modeler, so the history reads like a conversation: what changed, who asked for it, when.
3. Compile on every edit. The agent compiles as it goes against your live connections, so a draft that will not publish is caught while it is being written, not at merge time.
4. A pull request carries the change. When the draft is ready, Create pull request opens a PR whose title names what changed. The compile verdict is posted onto its head commit as a check, and the draft panel mirrors the PR's state.
5. Merge is the publish. When the PR merges to the base branch, the package publishes from that merge commit, and the new version records the commit it came from. For a git-backed package, this is the only way a version gets made.

The loop repeats. After a merge the draft re-cuts from the new base tip, ready for the next change. Fall behind main and Update from main absorbs the base branch, showing what it brought in. A direct upload over a git-backed package is refused, so a version can never exist without the commit that produced it.

What to Know Before Enrolling

• It is turned on per environment, and applies only going forward. Drafts created after it is turned on use it. Drafts that already exist keep working the way they were created and finish that way.
• One repository per environment. Each package is a top-level directory in it. You do not choose or create repositories per package.
• Text files only. A package containing a binary file, or any file over 1 MB, is refused up front with the files named. Keep large data in embedded data or your warehouse.
• Enrolled packages publish only through a proposal. cred publish and CI uploads still work for packages in environments that are not enrolled. For an enrolled package the same command is refused, and a proposal is the path whether or not anyone else reviews it.
• Attribution is permanent. Each change records the name and email of the person the agent was working for, and history is not rewritten afterwards. The toggle says so, so it is a decision made at enrollment rather than discovered later.

Set It Up

Setup has two halves. A repository is provisioned and registered to your environment. You enable the environment. Both are one-time.

cred update environment <environmentName> \
  --git-modeling true \
  --git-repository-owner <owner> \
  --git-repository-name <name> \
  --git-base-branch main

Related